Formatos

A CLI traduz dezoito formatos de ficheiro. O formato é inferido a partir da extensão do ficheiro; para o substituir, defina format numa entrada files[] — nos três formatos em que isso é sempre necessário (yaml-openapi, yaml-root-key, android).

npx degit lingodotdev/lingo.dev/demo/new-cli my-lingo-demo
cd my-lingo-demo

JSON e JSONC#

Tradução simples de chave/valor. Todos os valores de texto são traduzidos, a menos que um controlo de chave indique o contrário.

{ "pattern": "content/en/app.json", "lockedKeys": ["meta.version"] }

O JSONC também preserva os comentários, que o motor lê como contexto — veja notas para tradutores.

{ "pattern": "content/en/settings.jsonc", "preservedKeys": ["featureFlags"] }

Markdown, MDX e Markdoc#

A prosa do corpo é traduzida por predefinição. O frontmatter e os componentes incorporados não são traduzidos, a menos que opte por isso.

Frontmatter#

Liste os campos de frontmatter a traduzir com translateFrontmatterFields:

{
  "pattern": "content/en/guide.md",
  "translateFrontmatterFields": ["title", "description"]
}

Props de componentes MDX#

No MDX, pode traduzir props específicas em componentes específicos com translateComponentProps:

{
  "pattern": "content/en/landing.mdx",
  "translateFrontmatterFields": ["title"],
  "translateComponentProps": [{ "component": ["Hero", "Callout"], "props": ["title", "body"] }]
}

Isto traduz as props title e body em <Hero> e <Callout> e deixa todas as outras props intocadas.

Markdoc#

O Markdoc funciona como o Markdown, com o frontmatter e os atributos das tags preservados:

{
  "pattern": "content/en/changelog.mdoc",
  "translateFrontmatterFields": ["title"]
}

YAML#

O YAML genérico é detetado automaticamente a partir de .yaml/.yml — todos os valores de texto são traduzidos, e as chaves e a estrutura são preservadas:

{ "pattern": "content/en/strings.yaml" }

As especificações OpenAPI são um caso especial: partilham a extensão .yaml, mas precisam de um format explícito para que o motor traduza apenas os campos visíveis para utilizadores (resumos, descrições) e deixe intactas as chaves do schema, os paths e os IDs das operações:

{ "pattern": "content/en/api.yaml", "format": "yaml-openapi" }

Os ficheiros de idioma no estilo Rails são o outro caso especial: o idioma é a chave-raiz do YAML (en:) e o ficheiro de destino tem de ter o idioma de destino como raiz (es:). Também nestes casos, defina format explicitamente:

{ "pattern": "config/locales/en.yml", "format": "yaml-root-key" }

Formatos de aplicações e frameworks#

PO, Flutter ARB, Xcode .strings, Xcode .stringsdict, módulos de idioma TypeScript, XLIFF, SubRip e PHP seguem todos a mesma regra: o texto traduzível é traduzido, tudo o que é estrutural é preservado (chaves, IDs, metadados, placeholders, códigos de tempo, código, formatação). Cada um é detetado automaticamente pela extensão — basta apontar um padrão para o ficheiro de origem:

{ "pattern": "lib/l10n/app_en.arb" }
{ "pattern": "locales/en.po" }
{ "pattern": "Localizable.strings" }
{ "pattern": "l10n/en.xlf" }

Um deles precisa de um format explícito porque a extensão é demasiado ambígua para deteção automática:

{ "pattern": "res/values/strings.xml", "format": "android" }

Catálogos de Strings do Xcode#

Um ficheiro .xcstrings (Catálogo de Strings) contém todos os idiomas num único ficheiro. Não existe um caminho de saída por idioma — o CLI lê o idioma de origem e escreve cada destino de volta no mesmo ficheiro:

{ "pattern": "Localizable.xcstrings" }

As cadeias assinaladas com "shouldTranslate": false no catálogo são ignoradas — a CLI deixa-as sem tradução e inalteradas.

Caminhos de saída#

O padrão dá nome ao seu ficheiro de origem; todos os caminhos de destino são derivados a partir dele. Aplicam-se quatro regras, por esta ordem:

1. Um segmento completo do caminho ou nome de ficheiro correspondente ao idioma — o caso mais comum. content/en/app.json → content/de/app.json, locales/en.json → locales/de.json.
2. Um idioma no final de um segmento ou nome de ficheiro, para os esquemas que o representam dessa forma — Android, Xcode .strings/.stringsdict, Flutter e yaml-root-key. res/values-en/ → res/values-de/, app_en.arb → app_de.arb, devise.en.yml → devise.de.yml.
3. O nome reservado de uma plataforma para o idioma predefinido, sem qualquer idioma no caminho. O res/values/ simples do Android passa a res/values-de/, e o Base.lproj do Xcode passa a de.lproj.
4. O String Catalog, em que o caminho de destino é o caminho de origem, porque um único ficheiro reúne todos os idiomas.

O Android é a única plataforma cujos caminhos de destino não seguem o BCP 47: a CLI escreve o qualificador de recursos que o Android efetivamente lê, por isso pt-BR vai para values-pt-rBR/ e zh-Hans para values-b+zh+Hans/.

Se nenhuma das regras corresponder — se o idioma de origem não aparecer em parte alguma do caminho — a CLI cria, por defeito, uma pasta <locale>/ ao lado do ficheiro, e lingo push avisa que foi essa a opção assumida. Encare esse aviso como um sinal de que o padrão está incorreto. Consulte Configuration.

Vem do CLI legado?#

A maioria dos formatos do CLI legado já chegou ao CLI atual (PO, XLIFF, strings Android/Xcode, Flutter ARB e mais — veja a tabela acima). Alguns formatos menos comuns (por exemplo, CSV, HTML, MJML, .properties) ainda não são suportados; até o seu ser disponibilizado, a documentação do CLI legado cobre-o.