A CLI do Lingo.dev traduz ficheiros estáticos no seu repositório — Markdown, MDX, Markdoc, JSON, YAML, legendas e muito mais — através de um motor de localização configurado. Aponte-a para o seu conteúdo, execute uma vez e obtenha os ficheiros traduzidos ao lado dos originais.
Tipos de Conteúdo Suportados#
A CLI deteta o formato de cada ficheiro pela respetiva extensão — não há qualquer tipo de bucket para configurar. O idioma faz parte do caminho (content/en/x.md passa a content/de/x.md), por isso não é necessário o marcador [locale].
| Tipo de conteúdo | Formato | Caminho de exemplo |
|---|---|---|
| Documentação | Markdown | docs/en/getting-started.md |
| Documentação | MDX | docs/en/getting-started.mdx |
| Documentação | Markdoc | docs/en/getting-started.mdoc |
| Dados estruturados | JSON | data/en.json |
| Dados estruturados | YAML | data/en.yaml |
| Artigos de blogue | Markdown / MDX | blog/en/post-slug.md |
| Localização | Gettext PO | locale/en/messages.po |
| Localização | XLIFF | locale/en.xliff |
| Legendas | SRT | subs/en/intro.srt |
Consulte a Referência de formatos para ver a lista completa dos tipos de ficheiro suportados.
Ainda não suportado na nova CLI
CSV (csv-per-locale), legendas VTT, texto simples .txt e Java .properties ainda não são suportados pelo novo CLI. Para já, mantenha esses ficheiros no legacy CLI e acompanhe o registo de alterações para ficar a par das novidades.
Pré-requisitos#
Em cada execução, o conteúdo passa por um motor de localização — a configuração que define que modelo de LLM, glossário, voz da marca e regras se aplicam. Crie um no painel da Lingo.dev e, em seguida, configure a CLI (Node 22+):
npm install -g @lingo.dev/cli
lingo login
lingo init
lingo linklingo init e lingo link criam .lingo/config.json, ligando a CLI à sua organização e ao seu motor. Faça commit deste ficheiro para que todos os ambientes partilhem a mesma configuração.
{
"orgId": "org_abc123",
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "docs/en/getting-started.md" }]
}Em CI, ignore lingo login e forneça LINGO_API_KEY como variável de ambiente. Pode gerá-la a partir de chaves de API.
Sites de Documentação#
A maioria dos frameworks de documentação organiza o conteúdo traduzido em diretórios por idioma. Adicione um padrão por ficheiro de origem (ou um glob) a files. A CLI preserva o frontmatter, os blocos de código e a sintaxe dos componentes ao traduzir Markdown, MDX e Markdoc.
{
"orgId": "org_abc123",
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [
{ "pattern": "docs/en/getting-started.md" },
{ "pattern": "docs/en/setup.mdx" }
]
}Execute a primeira tradução para preencher todos os idiomas de destino:
lingo push --backfill-missingNas execuções seguintes, lingo push traduz apenas o que mudou. Use lingo pull para obter traduções produzidas noutro local.
Ajuste o caminho de origem para corresponder à convenção de diretórios do seu framework:
| Framework | Convenção de diretórios por idioma | Referência |
|---|---|---|
| Docusaurus | i18n/[locale]/docusaurus-plugin-content-docs/current/ | guia de i18n do Docusaurus |
| Nextra | Páginas por idioma ou dicionários JSON | documentação do Nextra |
| Hugo | content/[locale]/ | guia multilingue do Hugo |
| Astro | src/content/[locale]/ ou dicionários JSON | guia de i18n do Astro |
| VitePress | Prefixo de diretório [locale]/ | i18n do VitePress |
| MkDocs | docs/ por idioma com plugin de i18n | plugin de i18n do MkDocs |
Componentes MDX
A tradução de MDX preserva a sintaxe dos componentes JSX. Componentes personalizados como <Callout>, <Tabs> e <CodeBlock> passam sem alterações — apenas o conteúdo de texto no seu interior é traduzido.
Dados Estruturados#
Os ficheiros JSON e YAML são traduzidos automaticamente com base na respetiva extensão. Use controlos de chaves para impedir que valores não traduzíveis (IDs, URLs, flags de configuração) sejam alterados.
{
"orgId": "org_abc123",
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [
{ "pattern": "content/en.json" },
{ "pattern": "data/en.yaml" }
]
}O YAML genérico não precisa do campo format. Apenas yaml-openapi, yaml-root-key e android exigem um "format" explícito na entrada do ficheiro.
YAML com chave-raiz de idioma
Os ficheiros YAML que usam o código de idioma como chave-raiz (comum em Rails e Hugo) exigem um "format": "yaml-root-key" explícito — a chave-raiz é reescrita para o idioma de destino. Consulte a Referência de formatos.
Legendas#
Os ficheiros de legendas SRT são traduzidos com base na respetiva extensão. A CLI preserva todos os dados de temporização, os índices das legendas e as etiquetas de formatação — apenas o conteúdo de texto é traduzido.
{
"orgId": "org_abc123",
"engineId": "eng_abc123",
"sourceLocale": "en",
"targetLocales": ["es", "fr", "de", "ja"],
"files": [{ "pattern": "subs/en/intro.srt" }]
}VTT ainda não suportado
As legendas WebVTT (.vtt) ainda não são suportadas pela nova CLI. Mantenha os ficheiros VTT na legacy CLI e acompanhe o registo de alterações para novidades.
Trabalhar com Grandes Volumes de Conteúdo#
Os repositórios de conteúdo estático podem conter milhares de ficheiros. A CLI trata disso de forma eficiente:
| Mecanismo | Como ajuda |
|---|---|
| Estado da execução | .lingo/lock.json regista as impressões digitais do conteúdo de origem, por isso lingo push traduz apenas ficheiros novos ou alterados. Faça commit do ficheiro; ele é regenerado em cada push. |
| Paralelismo do lado do servidor | O motor trata da tradução em paralelo por si — não há nenhuma flag de concorrência para ajustar. |
| Execuções direcionadas | Limite uma execução a ficheiros específicos com um glob: lingo push "docs/en/**". |
Para verificar se as traduções estão atualizadas sem escrever ficheiros — útil como validação em CI — execute lingo check.
