Configuração da CLI

Defina a busca de arquivos de origem, as opções de tradução e os caminhos de destino em .lingo/config.json.

.lingo/config.json descreve quais arquivos o projeto traduz e onde os arquivos de destino devem ficar. A CLI procura a configuração mais próxima subindo pelos diretórios a partir do diretório de trabalho e usa essa raiz para resolver os caminhos relativos ao projeto. Os comandos locais de catálogo usam cwd quando não há configuração.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [{ "pattern": "locales/en.json" }]
}

Execute link para adicionar os IDs da organização e do engine de localização para tradução remota. A extração pode usar as configurações de i18n localmente, sem esses IDs. Use JSON estrito: comentários e vírgulas finais não são aceitos aqui.

Campos da raiz #

CampoSignificado
orgId, engineIdIDs de recursos não vazios; juntos, estabelecem o vínculo remoto.
sourceLocaleString não vazia que identifica o idioma de origem.
targetLocalesEntradas com strings não vazias; em tempo de execução, são removidas as duplicatas e a correspondência exata com o idioma de origem.
filesEntradas de origem descritas abaixo.
i18n.messagesPathDiretório do catálogo para extração/verificação/limpeza; padrão: locales.
i18n.typesPathCaminho da declaração para extração/verificação; padrão: lingo.d.ts.
github.workflows.onPushToDefaultBranch.enabledGatilho opcional de integração para o branch padrão.
github.workflows.onPullRequest.enabledGatilho opcional de integração para pull requests.
github.safety.requireApprovalConfiguração opcional de aprovação das execuções da integração.

Chaves desconhecidas na raiz e nas entradas de arquivo geram avisos e são ignoradas. Um erro de digitação pode manter um valor padrão em uso, em vez de causar a rejeição do arquivo inteiro.

Init grava as configurações de localização; link grava os IDs de vínculo; unlink remove apenas esses IDs. As operações de gravação preservam as outras seções da raiz, mas init --force recria as entradas de arquivo e descarta as opções avançadas. As configurações do GitHub não instalam o aplicativo nem fazem um push da CLI acionar a automação do repositório; use a configuração da integração.

Campos das entradas de arquivo #

CampoSignificado
patternUm padrão de origem não vazio.
includePadrões de origem; têm precedência sobre pattern, mesmo quando a lista está vazia.
excludePadrões excluídos desta entrada.
formatFormato definido explicitamente, escolhido na lista de formatos compatíveis abaixo.
localeFormatRepresentação do caminho em bcp47, underscore ou android.
targetPath, sourceRootModelo de saída e prefixo opcional a ser removido para [path].
translateFrontmatterFieldsCampos de metadados selecionados pelos processadores da família Markdown.
translateComponentPropsNomes de propriedades ou regras de propriedades filtradas por componente.
lockedKeys, preservedKeys, ignoredKeysArrays não vazios de caminhos de chaves para os processadores que oferecem suporte.
injectLocaleBooleano ou { "enabled": true, "key": "language" }.
keyColumnSomente CSV: cabeçalho da coluna de chaves; o padrão é a primeira célula do cabeçalho.
lockedPatternsSomente para arquivos de propriedades: expressões regulares RE2 presentes nos valores não são traduzidas.

Cada entrada precisa de pattern ou include; um include vazio não seleciona nada. A primeira entrada correspondente fornece as opções. Controles de chaves explica a responsabilidade pelos valores e os limites dos formatos.

Padrões de arquivo #

O mecanismo de correspondência aceita * dentro de um segmento e **/ entre diretórios. Use docs/en/**/* para uma subárvore recursiva; apenas ** no final não tem o mesmo significado. Não presuma que o comportamento de chaves ou extglob seja igual ao de outra biblioteca de glob.

json
{
  "sourceLocale": "en",
  "targetLocales": ["de"],
  "files": [
    {
      "include": ["docs/en/**/*.md", "docs/en/**/*.mdx"],
      "exclude": ["docs/en/private/**/*"]
    }
  ]
}

Uma exclusão vale apenas para sua entrada; outra entrada ainda pode incluir o arquivo. A busca de arquivos ignora .git e node_modules, mas não tudo em .gitignore. Os padrões posicionais de push restringem ainda mais as origens configuradas por interseção e alteram o modo de planejamento. Coloque-os entre aspas no shell.

Seleção de formato #

Os formatos configurados são json, jsonc, md, mdx, markdoc, yaml-openapi, po, flutter, xcode-strings, yaml, android, typescript, xcode-xcstrings, srt, xliff, xcode-stringsdict, php, yaml-root-key, html, txt, csv e properties.

SufixoFormato inferido
.json, .jsoncJSON ou JSONC.
.md, .mdx, .mdocMarkdown, MDX, Markdoc.
.html, .htmHTML.
.po, .arbGettext, Flutter.
.strings, .xcstrings, .stringsdictFormato Apple correspondente.
.ts, .mts, .ctsTypeScript.
.srt, .xlf, .xliff, .phpSubRip, XLIFF, PHP.
.txtTexto simples, somente com um padrão que termine em .txt ou com o formato txt.
.csvCSV, somente com um padrão que termine em .csv ou com o formato csv.
.propertiesArquivos de propriedades Java, apenas quando o padrão termina no formato .properties ou properties.
.yaml, .ymlDefina explicitamente yaml, yaml-root-key ou OpenAPI baseado em yaml.
.xmlDefina android explicitamente; XML genérico não é compatível.

Para OpenAPI, o identificador exato é yaml-openapi. Mesmo com a seleção explícita do formato, a descoberta continua limitada à lista de sufixos compatíveis. Um arquivo .txt, .csv ou .properties só pertence a uma entrada cujo padrão termine com essa extensão ou que defina o formato correspondente, txt, csv ou properties. Essa entrada seleciona apenas arquivos com essa extensão. Arquivos .js, .tsx, .pot, MJML e VTT não estão configurados como arquivos de entrada da CLI. A extração de React TSX é uma operação distinta.

A tradução de HTML aplica as alterações ao texto e aos atributos selecionados diretamente no código-fonte original, preservando a marcação, os comentários e a formatação dos trechos não alterados. Um elemento <html> explícito recebe o idioma de destino no atributo lang; fragmentos continuam sendo fragmentos. Consulte HTML para saber mais sobre a seleção de texto e o comportamento da saída.

Formatos descreve o comportamento dos analisadores, incluindo estruturas ignoradas e limites de reconstrução. Os processadores compartilhados do servidor não ampliam esta enumeração da CLI.

Caminhos de saída #

Use um modelo explícito quando os caminhos de origem não identificarem o idioma:

json
{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr"],
  "files": [
    {
      "pattern": "docs/**/*.md",
      "sourceRoot": "docs",
      "targetPath": "i18n/[locale]/docs/[path]"
    }
  ]
}

docs/start.md se torna i18n/de/docs/start.md e i18n/fr/docs/start.md. [locale] usa a representação de idioma da entrada; [path] remove a raiz de origem respeitando os limites dos segmentos. Uma raiz docs não remove parte de docsite.

Os modelos exigem [locale]; entradas glob também exigem [path]. Esses são os únicos marcadores de posição. Caminhos absolutos, .., raízes glob, raízes fora das entradas e saídas encontradas novamente como origens configuradas são rejeitados. sourceRoot sem targetPath é inválido. O push também verifica colisões de saída sem diferenciar maiúsculas de minúsculas.

Push, pull e purge também respeitam o sistema de arquivos: se uma origem, um destino, .lingo/lock.json ou .lingo/config.json apontar para fora da raiz do projeto ou para dentro de .git, por exemplo por meio de um link simbólico, o comando será interrompido com um erro antes de ler, gravar ou excluir qualquer conteúdo nesse local. Links que permanecem dentro do projeto continuam funcionando, mas não há gravação por meio de um destino ou Lockfile que seja, ele próprio, um link. Em um monorepo, execute os comandos a partir de uma raiz que contenha os arquivos compartilhados, em vez de criar links para eles a partir de um pacote.

Sem um modelo, a derivação tenta, nesta ordem: um diretório do idioma de origem, o nome-base completo do arquivo, estruturas de plataforma e, por fim, a inserção de um diretório de idioma, com um aviso. Os exemplos incluem locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → um destino .lproj e Android values → recursos qualificados por idioma. Leia os avisos e confirme que a aplicação carrega esse destino.

XCStrings e CSV armazenam todos os idiomas no arquivo de origem e rejeitam targetPath. As saídas de vários idiomas compartilham esse arquivo intencionalmente; a existência dele não comprova que cada idioma esteja presente. Purge ignora o arquivo compartilhado e, por isso, não pode remover entradas de idiomas individuais.

Selecionar metadados e texto de componentes #

Na família Markdown, a tradução seleciona title e description no frontmatter quando a opção é omitida. Uma lista vazia desativa a seleção; uma lista explícita seleciona outros campos. Caminhos aninhados para valores escalares e arrays exigem um frontmatter que possa ser analisado; se ele estiver malformado, o processamento pode recorrer à varredura do nível superior.

json
{
  "pattern": "docs/en/**/*.mdx",
  "translateFrontmatterFields": ["title", "description"],
  "translateComponentProps": ["aria-label", { "component": ["Card", "Callout"], "props": ["title"] }]
}

Uma string seleciona uma propriedade sem filtro de componente. Um objeto seleciona props e pode restringir os nomes dos componentes. Essas regras selecionam conteúdo literal traduzível, não o código do componente nem todos os atributos. Markdown, MDX e Markdoc têm comportamentos diferentes; verifique o processador ao mudar de caminho.

Para incluir orientações de tradução em JSONC, coloque @context imediatamente antes da string correspondente. A saída geral de JSONC mantém as marcas @orphan, mas descarta os outros comentários. Por isso, os metadados @src do React dependem da política de carregamento de catálogos; não presuma que o pull os preserve.

Para frameworks de documentação, escolha os diretórios reais de origem e saída separadamente do roteamento. OpenAPI usa yaml-openapi; raízes de idioma no estilo Rails usam yaml-root-key; YAML genérico usa yaml. A correspondência da extensão, por si só, não seleciona a semântica correta.

Idiomas #

A configuração verifica se as strings não estão vazias, em vez de validá-las com base em uma enumeração exaustiva de idiomas. Use os identificadores de que seu modelo e sua aplicação precisam, incluindo região ou sistema de escrita. localeFormat controla os caminhos: bcp47 mantém os hífens, underscore produz pt_BR e android produz formas como pt-rBR ou b+zh+Hans. O formato Android seleciona a representação Android, a menos que outra seja definida; isso também afeta a correspondência das origens.

Conclua as atualizações regulares pendentes nos arquivos de origem antes de adicionar um destino e preencher os arquivos ausentes dele. Adicionar um idioma explica como essa ordem mantém os idiomas existentes atualizados. Remover um destino interrompe sua seleção futura sem excluir os arquivos existentes. Metadados de idioma incorporados e catálogos compartilhados precisam seguir as regras dos respectivos processadores. Um caminho escrito corretamente não garante a direção do texto, o roteamento nem a qualidade linguística.

Caminhos do catálogo #

Para extração e verificação, --out/--types definidos explicitamente têm prioridade sobre as configurações de i18n, que, por sua vez, têm prioridade sobre os valores padrão. --source-locale usa en como padrão, independentemente de sourceLocale da localização. Alterar messagesPath não atualiza files[]; selecione o caminho JSONC gerado para tradução.

Monorepos #

Uma configuração na raiz pode compartilhar idiomas e um engine de localização entre caminhos de pacotes recursivos ou explícitos. Como alternativa, configurações por pacote podem manter idiomas, configurações e arquivos Lockfile independentes. Execute os comandos a partir da raiz do pacote desejado para que a busca pela configuração mais próxima não selecione inesperadamente uma configuração em um diretório ancestral.

Uma matriz de diretórios de CI deve preservar a saída coletada de cada projeto e evitar operações de gravação sobrepostas. Os ponteiros de execução locais no diretório pessoal dependem de raízes absolutas e não são compartilhados por um Lockfile. lingo check compara cada origem selecionada por files com o Lockfile no nível de arquivo; não verifica as chaves dentro dos arquivos.

Configuração de pontuação #

lingo score usa lingo.config.ts executável, carregado pelo Jiti. Essa configuração é separada do JSON do projeto e não registra carregadores locais arbitrários de formato. Mantenha os plugins confiáveis de pontuação separados das configurações remotas de localização de arquivos.