Formatos

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

Um ficheiro de idioma contém mais do que palavras. As chaves ligam as mensagens ao código, os marcadores de posição recebem valores da aplicação e a estrutura indica à framework como carregar o resultado. Um documento acrescenta títulos, ligações, exemplos e metadados. Traduzir ficheiros exige mudar o idioma sem perder essas ligações.

O Lingo.dev utiliza um processador de formato para selecionar o texto a traduzir e reconstruir o resultado. Escolha o processador em função do que o ficheiro representa. Um catálogo Rails e uma especificação OpenAPI podem ambos terminar em .yml, mas traduzir todas as cadeias de texto de um ou de outro causaria problemas diferentes: a raiz de idioma de um catálogo Rails tem de mudar, enquanto os identificadores de operações de uma API têm de permanecer inalterados.

Encontre o 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 AndroidandroidAndroid
Pacote de recursos de aplicação FlutterflutterFlutter ARB
Tabela de cadeias de texto da Applexcode-stringsApple strings
Plist de recursos de plural da Applexcode-stringsdictApple stringsdict
Catálogo da Apple com vários idiomasxcode-xcstringsCatálogos de cadeias de texto da Apple
Catálogo PO de GettextpoGettext
Documento de intercâmbio XLIFFxliffXLIFF
Legendas SubRipsrtSubRip
Texto simples, traduzido linha a linhatxtTexto simples
Documento ou fragmento HTMLhtmlHTML
Tabela CSV com uma coluna por idiomacsvCSV
Pacote de recursos de propriedades JavapropertiesPropriedades Java
Campos selecionados do CMS PayloadpayloadPayload

As referências descrevem os processadores de ficheiros existentes e os respetivos limites de extração e reconstrução. A CLI e a GitHub App aceitam os 22 tipos configurados acima, à exceção do Payload. O HTML é identificado a partir de .html e .htm; o resultado mantém intacto o conteúdo de origem que não foi alterado e define, num elemento <html> explícito, o valor de lang como o idioma de destino. Selecione explicitamente a variante YAML ou o formato Android pretendido na configuração do repositório. Tal como os Apple String Catalogs, o CSV mantém todos os idiomas no ficheiro de origem. O guia de início rápido da CLI acompanha o percurso de um ficheiro, desde a configuração até à obtenção; a secção GitHub aborda o workflow gerido do repositório.

As ligações atuais a fornecedores selecionam e escrevem conteúdo através dos seus próprios contratos de integração.

Para traduzir diretamente dados estruturados, envie JSON em linha. Para carregar ficheiros de origem e manter os respetivos formatos, siga o guia Documentos de ficheiro. Ambas as opções utilizam o mesmo ciclo de vida das tarefas de tradução.

Mantenha a versão de origem junto das respetivas traduções #

A tradução incremental de ficheiros compara a origem atual com uma versão anterior e utiliza a tradução de destino existente que lhe corresponde. Em conjunto, estes dados 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 texto idêntico em inglês e, ainda assim, manter traduções diferentes. As posições nos arrays, os números dos blocos de legendas, as posições das linhas de texto simples e a estrutura do documento também são usados para estabelecer a correspondência. Mover um item ou reorganizar um documento traduzido pode alterar essa correspondência, por isso mantenha as traduções de destino associadas à versão de origem a partir da qual foram produzidas.

A maioria dos formatos gera um ficheiro separado para cada idioma de destino. Já os catálogos de cadeias de texto da Apple reúnem os idiomas no ficheiro de origem. Um artefacto Payload ou um catálogo de cadeias de texto também pode conter alguns valores de destino e ter outros em falta. Verifique as entradas de destino propriamente ditas, não apenas a existência do ficheiro.

Controle separadamente a seleção de texto e o resultado #

Excluir texto da tradução pode ter vários significados. Um valor bloqueado no catálogo é obtido da origem; um valor preservado é obtido do destino existente; um valor ignorado pode desaparecer do resultado. O formato e a interface usada para a chamada determinam os controlos disponíveis.

Utilize os âmbitos 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 elementos fora da seleção, mas o tratamento das entradas que só existem na origem e das posições nos arrays depende do formato. Consulte a referência do respetivo formato para verificar o resultado completo.

Os metadados de contexto também têm um comportamento específico. Um comentário @context em JSONC descreve o valor de texto seguinte. Um @message.description em ARB descreve a respetiva mensagem. O msgctxt de Gettext distingue as mensagens e fornece contexto. Os comentários comuns podem ser mantidos na reconstrução sem se tornarem instruções de tradução. As anotações @src e @orphan de React fazem parte do seu workflow de manutenção de catálogos.

Depois de obter um ficheiro, carregue-o no sistema que o utiliza. Além do significado traduzido, verifique o idioma selecionado, as variáveis, as formas de plural, as ligações e os dados protegidos. Os guias de aplicação completam esse trabalho para aplicações Web, recursos nativos e conteúdo estático.