.XCSTRINGS - Catálogo de Strings da Apple (Strings)

O conteúdo de toda a Central de Ajuda é traduzido automaticamente de inglês pelo Phrase Language AI.

Extensões de arquivo	.xcstrings
Extensão de API	strings_catalog
Importar	Sim
Exportar	Sim
Suporte para formas plurais	Sim
Suporte para descrição	Sim
Opções de formato Essas opções podem ser especificadas quando um arquivo é carregado e/ou baixado. Dependendo do método de upload/download (API, CLI, sincronização de repositório, etc.), essas opções podem ser especificadas em parâmetros de consulta `Upload`, `Download` ou no arquivo de configuração `phrase.yml`.	convert_placeholder default_extraction_state locale_code_mapping

Catálogo de Strings da Apple (.xcstrings) é um formato de localização introduzido no Xcode 15. Ele aprimora a maneira como os desenvolvedores gerenciam strings localizadas ao suportar formatos estruturados para lidar com pluralização, variações específicas de dispositivo e muito mais. Este formato está se tornando a abordagem recomendada para gerenciar localizações em aplicativos iOS e macOS.

Os campos de metadados comment, extractionState e shouldTranslate são importados e exportados na ordem necessária para garantir a compatibilidade com o Xcode.

O Phrase também mapeia estados de tradução do Xcode para os equivalentes de Strings mais próximos durante a importação e os converte de volta para valores compatíveis com o Xcode na exportação. Se nenhum mapeamento específico se aplicar, traduzido é usado como o valor de exportação padrão. Se necessário, use a opção Ignorar estado de tradução na importação para pular o mapeamento de estado.

Amostra de código

{
  "sourceLanguage": "en",
  "strings": {
    "Sync Warning": {
      "comment": "Sync function unavailable message",
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "Cloud Sync must be enabled to use this feature."
          }
        },
        "fr": {
          "stringUnit": {
            "state": "translated",
            "value": "La synchronisation cloud doit être activée pour utiliser cette fonction."
          }
        }
      }
    },
    "Chosen Collections": {
      "comment": "View title indicating selected photo collections",
      "localizations": {
        "fr": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld collection sélectionnée"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld collections sélectionnées"
                }
              }
            }
          }
        },
        "en": {
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Collection Selected"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%ld Collections Selected"
                }
              }
            }
          }
        }
      }
    },
    "Settings Hub": {
      "localizations": {
        "es": {
          "stringUnit": {
            "state": "translated",
            "value": "Centro de configuración"
          }
        }
      }
    }
  },
  "version": 1.0.
}

Ao usar a CLI do Phrase, as exportações de arquivo seguem a estrutura definida no arquivo de configuração .phrase.yml. Para garantir que vários idiomas sejam exportados para um único arquivo .XCSTRINGS durante operações de pull:

Especifique apenas um destino de arquivo no arquivo de configuração da CLI.
Use o parâmetro locale_ids para listar todas as localidades de idioma incluídas na exportação.

Exemplo de configuração .phrase.yml

pull:
  targets:
    - file: ./i18n-test/Localizable.xcstrings
      params:
        locale_id: en # Main language for the download
        locale_ids: # Additional languages to include
          - de
          - es
          - fr 
        file_format: strings_catalog

Variações de dispositivo

O Catálogo de Strings da Apple suporta variações de dispositivo, que permitem conteúdos de tradução diferentes para a mesma chave, dependendo do dispositivo Apple que está sendo usado.

Para lidar com variações de dispositivo no Phrase Strings, chaves separadas são criadas para cada dispositivo usando o separador |==|. Ao importar arquivos .XCSTRINGS, o tipo de dispositivo é adicionado ao nome da chave base usando este separador.

Exemplo

A chave chamada %lld Product(s) Ordered para o dispositivo applewatch é importada como uma chave plural chamada %lld Product(s) Ordered|==|device.applewatch no Phrase Strings.

Durante a exportação, o Phrase Strings detecta a variante do dispositivo usando o separador e restaura sua estrutura aninhada original para o formato de localização da Apple.

{
  "sourceLanguage": "en",
  "strings": {
    "%lld Product(s) Ordered": {
      "comment": "Indica o número de produtos pedidos, com variações específicas para cada dispositivo",
      "localizations": {
        "en": {
          "variations": {
            "device": {
              "applewatch": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (Apple Watch)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (Apple Watch)"
                      }
                    }
                  }
                }
              },
              "ipad": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (iPad)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (iPad)"
                      }
                    }
                  }
                }
              },
              "iphone": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (iPhone)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (iPhone)"
                      }
                    }
                  }
                }
              },
              "mac": {
                "variations": {
                  "plural": {
                    "one": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Product ordered (Mac)"
                      }
                    },
                    "other": {
                      "stringUnit": {
                        "state": "translated",
                        "value": "%lld Products ordered (Mac)"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "fr": {
          "variations": {
            "plural": {
              "few": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit(s) commandé(s)"
                }
              },
              "many": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produits commandés"
                }
              },
              "one": {
                "stringUnit": {
                  "state": "translated",
                  "value": "%lld produit commandé"
                }
              }
            }
          }
        }
      }
    }
  }
}

Substituições de string

O Catálogo de Strings da Apple suporta substituições de string que fornecem marcadores flexíveis para conteúdo dinâmico.

Para lidar com substituições de string no Phrase Strings, chaves separadas são criadas usando o separador |==|. Ao importar arquivos .XCSTRINGS, a substituição é adicionada ao nome da chave base usando este separador.

O Phrase Strings também suporta a criação de strings de substituição diretamente no projeto. Quando estruturas de substituição são criadas manualmente, uma chave base e uma chave de substituição correspondente devem ser definidas para garantir que o formato aninhado correto seja gerado durante a exportação.

Substituições sempre exigem um formato de nomeação de chave específico: keyName|==|substitution.[specifier].

Exemplo: Importando estruturas de substituição de arquivos .XCSTRINGS existentes

A chave chamada birdSightingAlert para a substituição BIRDS é importada como uma chave plural chamada birdSightingAlert|==|substitution.BIRDS no Phrase Strings.

Durante a exportação, o Phrase Strings detecta a substituição usando o separador e restaura sua estrutura aninhada original para o formato de localização da Apple.

"birdSightingAlert": {
  "comment": "Alert message indicating the number of birds spotted",
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "new",
        "value": "You spotted %#@BIRDS@!"
      },
      "substitutions": {
        "BIRDS": {
          "formatSpecifier": "BIRDS",
          "variations": {
            "plural": {
              "one": {
                "stringUnit": {
                  "state": "new",
                  "value": "a bird"
                }
              },
              "other": {
                "stringUnit": {
                  "state": "new",
                  "value": "several birds"
                }
              },
              "zero": {
                "stringUnit": {
                  "state": "new",
                  "value": "no birds"
                }
              }
            }
          }
        }
      }
    }
  }

Exemplo: Criando strings de substituição do zero

Chave base

Uma chave base chamada keyName representa a string de formato de nível superior que contém o marcador de substituição %#@format@.

Quando exportada, esta chave é escrita como a stringUnit primária para a entrada:
```
"keyName": {
  "localizations": {
    "en": {
      "stringUnit": {
        "state": "translated",
        "value": "%#@format@"
      }
    }
  }
}
```

Chave de substituição

Uma string de substituição é definida como uma chave separada usando o formato de nomenclatura de substituição: keyName|==|substitution.li.

Esta chave contém o texto de substituição, normalmente com variações de plural. Durante a exportação, o Phrase Strings detecta a substituição usando o separador |==|substitution. e restaura a estrutura aninhada correspondente sob a chave base:

{
  "sourceLanguage": "en",
  "strings": {
    "keyName": {
      "localizations": {
        "en": {
          "stringUnit": {
            "state": "translated",
            "value": "%#@format@"
          },
          "substitutions": {
            "li": {
              "formatSpecifier": "li",
              "variations": {
                "plural": {
                  "one": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ day"
                    }
                  },
                  "other": {
                    "stringUnit": {
                      "state": "translated",
                      "value": "%@ days"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "version": 1.0.
}

Opções de formato

Identificador	convert_placeholder
Tipo	Booleano
Upload	Não
Download	Sim
Padrão	false
Descrição	O placeholder será convertido para corresponder aos requisitos específicos do formato. Exemplo: `$s`→`$@`, `%s`→`%@`

Identificador	default_extraction_state
Tipo	string
Upload	Não
Download	Sim
Padrão	null
Descrição	Define o valor de `extractionState` gravado nas chaves no arquivo exportado quando nenhum estado de extração já está definido na chave. Se uma chave já contiver um `extractionState`, seu valor será preservado durante a exportação. Compatível com: Downloads da interface do usuário API CLI (via configuração `.phrase.yml`) e Repo Sync

Identificador	locale_code_mapping
Tipo	objeto
Upload	Sim
Baixar	Sim
Padrão	}
Descrição	Mapeia códigos de localidade do Phrase para os códigos de localidade gravados no arquivo .XCSTRINGS. Cada chave é o código de localidade do Phrase; cada valor é o código gravado no arquivo, por exemplo: { "en": "en-GB", "fr": "fr-FR" } No download, o Phrase reescreve o campo `sourceLanguage` e qualquer chave de `localizations` que corresponda a uma chave de mapeamento para o valor mapeado. Códigos sem um mapeamento permanecem inalterados. No upload, o Phrase aplica o mesmo mapeamento de forma inversa e converte os códigos de localidade do arquivo de volta para os códigos de localidade correspondentes do Phrase, incluindo `sourceLanguage`. Esta opção afeta apenas os códigos de localidade lidos e gravados no próprio arquivo .XCSTRINGS. O mapeamento de localidade baseado em nome de arquivo, usado por exemplo em padrões de nomenclatura de arquivos de integração com Git, é uma configuração separada que mapeia caminhos de arquivo em vez dos códigos dentro do .XCSTRINGS.

Migrando de iOS Strings (.strings) para o Catálogo de Strings da Apple (.xcstrings)

O formato legado iOS Strings (.strings) trata uma sequência literal de barra invertida-n (\\n) no conteúdo da tradução como equivalente a uma quebra de linha real. Como resultado, as traduções criadas ou editadas durante o uso do formato .strings podem conter o texto literal \\n em vez de um caractere de quebra de linha real.

O Strings Catalog (.xcstrings) é um formato baseado em JSON. Quando o conteúdo que contém uma sequência literal \\n é exportado para .xcstrings, a codificação JSON escapa esse texto literal como \\\\n no arquivo. Este comportamento não é um erro de escape duplo. Ele reflete o texto literal \\n já presente no conteúdo da tradução, exportado usando o escape JSON correto.

Para resolver isso após a migração de .strings para .xcstrings, substitua as sequências literais \\n no conteúdo afetado por quebras de linha reais:

Exporte o conteúdo como de costume.
Abra o arquivo exportado em um editor de texto.
Substitua todas as instâncias da sequência literal \\n por uma quebra de linha real.
Reimporte o arquivo.

A busca e substituição no aplicativo não suporta a inserção de uma quebra de linha real, portanto, essa substituição deve ser realizada em um editor de texto externo antes de reimportar o arquivo.