Configuração da CLI

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

.lingo/config.json define os ficheiros que um projeto traduz e onde devem ficar as respetivas traduções. A CLI procura a configuração mais próxima nos diretórios ascendentes, 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 existe configuração.

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

Execute link para adicionar os IDs da organização e do motor de localização necessários à tradução remota. A extração pode usar as definições de i18n localmente sem esses IDs. Use JSON estrito: não são aceites comentários nem vírgulas finais.

Campos da raiz #

CampoSignificado
orgId, engineIdIDs de recursos não vazios; em conjunto, estabelecem a associação remota.
sourceLocaleCadeia de carateres não vazia que identifica o idioma de origem.
targetLocalesEntradas com cadeias de carateres não vazias; durante a execução, são removidos os duplicados 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 e limpeza; predefinição: locales.
i18n.typesPathCaminho da declaração para extração e verificação; predefinição: lingo.d.ts.
github.workflows.onPushToDefaultBranch.enabledGatilho opcional da integração para o ramo predefinido.
github.workflows.onPullRequest.enabledGatilho opcional da integração para pedidos de integração.
github.safety.requireApprovalDefinição opcional de aprovação das execuções da integração.

As chaves desconhecidas na raiz e nas entradas de ficheiros geram avisos e são ignoradas. Um erro de escrita pode manter um valor predefinido em vigor, em vez de provocar a rejeição de todo o ficheiro.

O comando init escreve as definições de localização; link escreve os IDs de associação; unlink remove apenas esses IDs. As operações de escrita preservam as outras secções da raiz, mas init --force reconstrói as entradas de ficheiros e perde as opções avançadas. As definições do GitHub não instalam a aplicação nem fazem com que um push da CLI acione a automatização do repositório; use a configuração da integração.

Campos das entradas de ficheiros #

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, da lista de formatos suportados abaixo.
localeFormatRepresentação do caminho em bcp47, underscore ou android.
targetPath, sourceRootModelo de saída e prefixo opcional a remover para [path].
translateFrontmatterFieldsCampos de metadados selecionados pelos processadores da família Markdown.
translateComponentPropsNomes de propriedades ou regras de propriedades com filtro por componente.
lockedKeys, preservedKeys, ignoredKeysListas não vazias de caminhos de chaves para os processadores que as suportam.
injectLocaleBooleano ou { "enabled": true, "key": "language" }.
keyColumnApenas CSV: cabeçalho da coluna de chaves; por predefinição, a primeira célula do cabeçalho.
lockedPatternsApenas para ficheiros de propriedades: as expressões regulares RE2 presentes nos valores mantêm-se sem tradução.

Cada entrada precisa de pattern ou include; um include vazio não seleciona nada. As opções são definidas pela primeira entrada correspondente. Controlos de chaves explica a quem pertencem os valores e os limites dos formatos.

Padrões de ficheiros #

O mecanismo de correspondência suporta * dentro de um segmento e **/ entre diretórios. Use docs/en/**/* para uma subárvore recursiva; um ** isolado no final não tem o mesmo efeito. Não assuma que as chavetas ou extglob se comportam como noutra biblioteca de padrões glob.

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

Uma exclusão aplica-se apenas à respetiva entrada; outra entrada pode continuar a incluir o ficheiro. A deteção ignora .git e node_modules, mas não tudo o que está em .gitignore. Os padrões posicionais de push restringem ainda mais a seleção à interseção com as origens configuradas e alteram o modo de planeamento. Coloque-os entre aspas na linha de comandos.

Seleção do 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, apenas com um padrão que termine em .txt ou com o formato txt.
.csvCSV, apenas com um padrão que termine em .csv ou com o formato csv.
.propertiesFicheiros 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 é suportado.

Para OpenAPI, o identificador exato é yaml-openapi. Mesmo com a seleção explícita do formato, continua a aplicar-se a lista de sufixos suportados pela deteção. Um ficheiro .txt, .csv ou .properties só pode pertencer a uma entrada cujo padrão termine nessa extensão ou que defina o formato correspondente, txt, csv ou properties. Essa entrada seleciona apenas ficheiros com essa extensão. Os ficheiros .js, .tsx, .pot, MJML e VTT não estão configurados como ficheiros de entrada da CLI. A extração de React TSX é uma operação distinta.

A tradução de HTML atualiza o texto e os atributos selecionados diretamente no código-fonte original, preservando a marcação, os comentários e a formatação que não foram alterados. Um elemento <html> explícito recebe o idioma de destino no atributo lang; os fragmentos mantêm-se como fragmentos. Consulte HTML para saber mais sobre a seleção de texto e o comportamento da saída.

Formatos descreve o comportamento do analisador, incluindo as estruturas ignoradas e os limites de reconstrução. Os processadores partilhados do servidor não alargam esta enumeração da CLI.

Caminhos de saída #

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

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

docs/start.md passa a i18n/de/docs/start.md e i18n/fr/docs/start.md. [locale] usa a representação do idioma definida na 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]; as entradas glob também exigem [path]. Estes são os únicos marcadores de posição. São rejeitados caminhos absolutos, .., raízes glob, raízes fora das entradas e saídas novamente detetadas como origens configuradas. sourceRoot sem targetPath é inválido. O comando push também verifica colisões entre saídas sem distinguir maiúsculas de minúsculas.

Os comandos push, pull e purge também têm em conta o sistema de ficheiros: se uma origem, um destino, .lingo/lock.json ou .lingo/config.json resolver para um caminho fora da raiz do projeto ou dentro de .git, por exemplo através de uma ligação simbólica, o comando termina com um erro antes de ler, escrever ou eliminar qualquer conteúdo nesse local. As ligações que permanecem dentro do projeto continuam a funcionar, mas não é feita qualquer escrita através de um destino ou Lockfile que seja, ele próprio, uma ligação. Num monorrepositório, execute os comandos a partir de uma raiz que contenha os ficheiros partilhados, em vez de criar ligações para esses ficheiros a partir de um pacote.

Sem um modelo, a derivação tenta, por esta ordem, um diretório do idioma de origem, o nome completo do ficheiro sem extensão e as estruturas das plataformas; por fim, insere um diretório de idioma e emite um aviso. Alguns exemplos: locales/en.json → locales/de.json, app_en.arb → app_de.arb, Base.lproj → um .lproj de destino e, em Android, values → recursos qualificados pelo idioma. Leia os avisos e confirme que a aplicação carrega esse destino.

XCStrings e CSV guardam todos os idiomas no ficheiro de origem e rejeitam targetPath. As saídas de vários idiomas partilham intencionalmente esse ficheiro; a sua existência não garante que todos os idiomas estejam presentes. Purge ignora o ficheiro partilhado, pelo que não pode remover entradas de idiomas individuais.

Selecionar metadados e texto de componentes #

Quando a opção é omitida, a tradução de formatos da família Markdown seleciona os campos title e description dos metadados iniciais. Uma lista vazia desativa a seleção; uma lista explícita seleciona outros campos. Os caminhos aninhados de valores escalares e listas exigem metadados iniciais que possam ser analisados; se estes estiverem malformados, a análise pode limitar-se ao nível superior.

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

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

Para fornecer orientações ao tradutor em JSONC, coloque @context imediatamente antes da respetiva cadeia de carateres. A saída JSONC geral mantém as marcas @orphan, mas remove os outros comentários. Por isso, os metadados @src do React exigem a política de carregamento do catálogo; não se deve assumir que o comando pull os preserva.

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

Idiomas #

A configuração valida cadeias de carateres não vazias, em vez de as comparar com uma enumeração exaustiva de idiomas. Use os identificadores de que o modelo e a aplicação precisam, incluindo a região ou o sistema de escrita. localeFormat controla os caminhos: bcp47 mantém os hífenes, underscore produz pt_BR e android produz formas como pt-rBR ou b+zh+Hans. O formato Android seleciona a representação Android, salvo indicação em contrário; isto também afeta a correspondência das origens.

Conclua as atualizações normais pendentes dos ficheiros de origem antes de adicionar um destino e preencher os ficheiros que lhe faltam. Adicionar um idioma explica como esta ordem mantém os idiomas existentes atualizados. Remover um destino impede a sua seleção futura sem eliminar os ficheiros existentes. Os metadados de idioma incorporados e os catálogos partilhados seguem as regras do respetivo processador. Um caminho escrito corretamente não garante a direção do texto, o encaminhamento nem a qualidade linguística.

Caminhos do catálogo #

Para extração e verificação, os valores explícitos de --out/--types têm precedência sobre as definições de i18n; na ausência de ambos, aplicam-se as predefinições. --source-locale usa en por predefinição, independentemente da definição de localização sourceLocale. Alterar messagesPath não atualiza files[]; selecione o caminho JSONC gerado para tradução.

Monorrepositórios #

Uma configuração na raiz permite partilhar idiomas e um motor de localização entre caminhos de pacotes recursivos ou explícitos. Em alternativa, as configurações por pacote permitem manter os idiomas, a configuração e os Lockfiles independentes. Execute os comandos a partir da raiz do pacote pretendido, para evitar que a deteção da configuração mais próxima selecione inesperadamente uma configuração num diretório ascendente.

Uma matriz de diretórios de CI deve preservar a saída recolhida de cada projeto e evitar operações de escrita sobrepostas. Os apontadores de execução locais no diretório pessoal dependem de raízes absolutas e não são partilhados através de um Lockfile. lingo check compara cada origem selecionada por files com o Lockfile ao nível do ficheiro; não verifica as chaves no seu interior.

Configuração da pontuação #

lingo score usa o ficheiro executável lingo.config.ts, carregado através de Jiti. Esta configuração é independente do JSON do projeto e não regista carregadores locais de formatos arbitrários. Mantenha os módulos de pontuação de confiança separados das definições remotas de localização de ficheiros.