Formatos

Encontre o processador de arquivos que traduz seu texto sem alterar a estrutura de que sua aplicação precisa.

Um arquivo de idioma contém mais do que palavras. Suas chaves conectam mensagens ao código, suas variáveis de substituição recebem valores da aplicação e sua estrutura indica ao framework como carregar o resultado. Um documento traz ainda títulos, links, exemplos e metadados. A tradução de arquivos precisa mudar o idioma sem perder essas conexões.

O Lingo.dev usa um processador de formato para selecionar o texto a traduzir e reconstruir o resultado. Escolha o processador com base no que o arquivo representa. Um catálogo Rails e uma especificação OpenAPI podem ter a mesma extensão .yml, mas traduzir todas as strings de um ou de outro causaria problemas diferentes: a raiz de idioma do Rails precisa mudar, enquanto os identificadores de operação de uma API devem permanecer inalterados.

Encontre seu formato #

OrigemTipo de processadorReferência
Catálogo JSON aninhadojsonJSON
JSON com comentários de contextojsoncJSONC
Catálogo YAMLyamlYAML
YAML com uma única raiz de idiomayaml-root-keyYAML com raiz de idioma
Módulo estático de idioma em TypeScripttypescriptTypeScript
Array estático de idioma em PHPphpPHP
Documento MarkdownmdMarkdown
Markdown com componentes JSXmdxMDX
Documento MarkdocmarkdocMarkdoc
YAML OpenAPI 3.xyaml-openapiOpenAPI
XML de recursos do AndroidandroidAndroid
Pacote de recursos de aplicação do FlutterflutterFlutter ARB
Tabela de strings da Applexcode-stringsStrings da Apple
Plist de recursos de plural da Applexcode-stringsdictStringsdict da Apple
Catálogo da Apple com vários idiomasxcode-xcstringsCatálogos de strings da Apple
Catálogo PO do GettextpoGettext
Documento de intercâmbio XLIFFxliffXLIFF
Legendas SubRipsrtSubRip
Texto simples, traduzido linha por linhatxtTexto simples
Documento ou fragmento HTMLhtmlHTML
Tabela CSV com uma coluna por idiomacsvCSV
Pacote de recursos de propriedades JavapropertiesPropriedades Java
Campos selecionados do Payload CMSpayloadPayload

As referências descrevem os processadores de arquivos já definidos, incluindo seus limites de extração e reconstrução. A CLI e o GitHub App aceitam os 22 tipos configurados listados acima, com exceção do Payload. O formato HTML é identificado a partir de .html e .htm; a saída preserva o conteúdo original sem alterações e define o lang de um elemento <html> explícito como o idioma de destino. Selecione explicitamente a variante YAML ou o formato Android desejado na configuração do repositório. Assim como Apple String Catalogs, o CSV mantém todos os idiomas no arquivo de origem. O guia de início rápido da CLI mostra o percurso de um arquivo, da configuração à recuperação; a seção GitHub aborda o workflow gerenciado do repositório.

As conexões atuais com provedores selecionam e gravam conteúdo por meio de seus próprios contratos de integração.

Para traduzir dados estruturados diretamente, envie JSON em linha. Para enviar arquivos de origem e preservar seus formatos, siga o guia Documentos de arquivo. As duas opções usam o mesmo ciclo de vida das tarefas de tradução.

Mantenha a versão de origem junto com suas traduções #

A tradução incremental de arquivos compara o conteúdo de origem atual com uma versão anterior e usa a tradução existente correspondente. Juntas, essas entradas permitem manter a redação aprovada das mensagens que não mudaram e traduzir as mensagens novas ou alteradas.

As chaves tornam essa comparação útil: checkout.title e account.title podem conter textos idênticos em inglês e ainda assim manter traduções diferentes. As posições em arrays, os números dos blocos de legenda, as posições das linhas de texto simples e a estrutura do documento também são usados na correspondência. Mover um item ou reorganizar um documento traduzido pode alterar essa correspondência. Por isso, mantenha as traduções associadas à versão de origem a partir da qual foram produzidas.

A maioria dos formatos gera um arquivo separado para cada idioma de destino. Já os catálogos de strings da Apple reúnem os idiomas no arquivo de origem. Um artefato do Payload ou um catálogo de strings também pode conter alguns valores de destino, mas ainda ter outros faltando. Confira as entradas de destino em si, não apenas a existência do arquivo.

Controle separadamente a seleção de texto e a saída #

Excluir texto da tradução pode ter vários significados. Um valor bloqueado no catálogo vem da origem; um valor preservado vem da tradução existente; um valor ignorado pode desaparecer da saída. O formato e a interface de chamada determinam quais controles estão disponíveis.

Use os escopos de chaves da CLI para JSON/JSONC, YAML, YAML com raiz de idioma, PHP e TypeScript. Uma atualização parcial mantém a redação existente no destino para os itens fora da seleção, mas o tratamento das entradas presentes apenas na origem e das posições em arrays depende do formato. Confira o resultado completo com o apoio da referência do formato.

Os metadados de contexto também têm comportamentos específicos. Um comentário @context em JSONC descreve o próximo valor de string. Um @message.description em ARB descreve a mensagem correspondente. O msgctxt do Gettext diferencia as mensagens e fornece contexto. Comentários comuns podem ser mantidos na reconstrução sem se tornarem instruções de tradução. As anotações @src e @orphan do React pertencem ao seu workflow de manutenção de catálogo.

Depois de obter um arquivo, carregue-o no sistema que o utiliza. Além do sentido da tradução, confira o idioma selecionado, as variáveis, as formas de plural, os links e os dados protegidos. Os guias de aplicação complementam esse trabalho para aplicações web, recursos nativos e conteúdo estático.