Configuração do i18n.json

i18n.json é o arquivo de configuração que controla o CLI da Lingo.dev e as integrações de CI/CD. Ele define quais idiomas traduzir, onde fica o conteúdo traduzível e qual backend de tradução usar.

Exemplo mínimo#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

O campo $schema habilita autocomplete e validação na IDE. O campo version acompanha a versão do schema para garantir compatibilidade com migrações automáticas.

Idioma#

A seção locale define os idiomas de origem e de destino:

json

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  }
}

Campo	Descrição
`locale.source`	O idioma em que seu conteúdo de origem foi escrito. Todas as traduções partem desse idioma.
`locale.targets`	Array de idiomas de destino. Cada idioma de destino gera um arquivo separado (ou uma seção), dependendo do formato do bucket.

Os códigos de idioma seguem o padrão BCP 47 — en, en-US, es-ES, zh-Hans e formatos específicos de plataforma, como o en-rUS do Android, são compatíveis.

Para listar os códigos de idioma disponíveis:

bash

npx lingo.dev@latest show locale sources   # Available source languages
npx lingo.dev@latest show locale targets   # Available target languages

Buckets#

Buckets definem padrões de descoberta de arquivos e regras de processamento. Cada chave de bucket especifica um formato de arquivo, e seu valor determina quais arquivos incluir ou excluir:

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

Campo	Descrição
`include`	Array de padrões de arquivo com o placeholder `[locale]`. Suporta curingas glob (`*`).
`exclude`	Opcional. Array de padrões que devem ser ignorados durante o processamento.
`lockedKeys`	Opcional. Chaves cujos valores são copiados da origem sem tradução. Consulte Key Locking.
`ignoredKeys`	Opcional. Chaves totalmente excluídas da tradução — elas não aparecem nos arquivos de destino. Consulte Key Ignoring.
`preservedKeys`	Opcional. Chaves inicializadas uma única vez a partir da origem e depois protegidas contra atualizações automáticas. Consulte Key Preserving.
`injectLocale`	Opcional. Chaves em que o código do idioma de destino é inserido automaticamente.

Padrões de inclusão#

Os padrões de inclusão usam o placeholder [locale], que é resolvido para os códigos de idioma configurados em tempo de execução:

locales/[locale].json → locales/en.json, locales/es.json
docs/[locale]/*.md → docs/en/*.md, docs/es/*.md

Padrões glob recursivos (**/*.json) não são compatíveis. Em vez disso, use caminhos de diretório explícitos.

Delimitadores de idioma personalizados#

Por padrão, os códigos de idioma em nomes de arquivo usam hífen (-) como delimitador: en-US.json. Para usar underscores no lugar, passe um objeto com o campo delimiter:

json

{
  "include": [
    "standard/[locale].json",
    { "path": "legacy/[locale].json", "delimiter": "_" }
  ]
}

Isso gera legacy/en_US.json em vez de legacy/en-US.json.

Notação de caminho de chave#

Os arrays lockedKeys, ignoredKeys e preservedKeys usam barra (/) para indicar chaves aninhadas e asterisco (*) para curingas:

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

Para ver a lista completa de tipos de bucket compatíveis, consulte Supported Formats.

Provedor#

A seção provider configura um provedor LLM direto para tradução. Esta seção é opcional — quando omitida, o CLI usa um engine de localização na Lingo.dev.

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

Campo	Descrição
`provider.id`	Identificador do provedor: `openai`, `anthropic`, `google`, `mistral`, `openrouter` ou `ollama`.
`provider.model`	Nome do modelo no provedor (por exemplo, `gpt-4o-mini`, `claude-3-haiku`).
`provider.prompt`	Prompt de sistema. `{source}` e `{target}` são substituídos pelos códigos de idioma em tempo de execução.
`provider.baseUrl`	Opcional. Endpoint de API personalizado (obrigatório para Ollama: `http://localhost:11434`).

Conexão com o engine#

Para direcionar as traduções por um engine de localização específico, adicione o campo engineId:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Quando engineId está definido, toda solicitação de tradução aplica automaticamente a voz da marca, o glossário, as instruções e a configuração de modelo do seu engine. Se ele for omitido e LINGO_API_KEY estiver definido, o CLI usa o engine padrão da sua organização.

Para o guia completo de configuração, consulte Connect Your Engine.

Variáveis de ambiente#

Variável	Obrigatório	Descrição
`LINGO_API_KEY`	Para o Lingo.dev Engine	Sua chave de API da Lingo.dev.
`LINGO_API_URL`	Não	URL base personalizada da API (para self-hosted ou staging).
`OPENAI_API_KEY`	Para o provedor OpenAI	Chave de API da OpenAI.
`ANTHROPIC_API_KEY`	Para o provedor Anthropic	Chave de API da Anthropic.
`GOOGLE_API_KEY`	Para o provedor Google	Chave de API do Google.
`MISTRAL_API_KEY`	Para o provedor Mistral	Chave de API da Mistral.
`OPENROUTER_API_KEY`	Para o provedor OpenRouter	Chave de API da OpenRouter.

Exemplo completo#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Migração de versão#

O CLI migra automaticamente configurações mais antigas de i18n.json para a versão mais recente do schema. Ele cria um backup do arquivo atual, atualiza o schema e preserva todas as configurações. Nenhuma intervenção manual é necessária.

Próximos passos#

Supported Formats

Todos os tipos de bucket e como configurá-los

i18n.lock

Como o lockfile acompanha o estado da tradução

Connect Your Engine

Direcione traduções pelo seu engine de localização

Setup

Instale o CLI e comece a usar

Exemplo mínimo#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

O campo $schema habilita autocomplete e validação na IDE. O campo version acompanha a versão do schema para garantir compatibilidade com migrações automáticas.

Idioma#

A seção locale define os idiomas de origem e de destino:

json

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  }
}

Campo	Descrição
`locale.source`	O idioma em que seu conteúdo de origem foi escrito. Todas as traduções partem desse idioma.
`locale.targets`	Array de idiomas de destino. Cada idioma de destino gera um arquivo separado (ou uma seção), dependendo do formato do bucket.

Os códigos de idioma seguem o padrão BCP 47 — en, en-US, es-ES, zh-Hans e formatos específicos de plataforma, como o en-rUS do Android, são compatíveis.

Para listar os códigos de idioma disponíveis:

bash

npx lingo.dev@latest show locale sources   # Available source languages
npx lingo.dev@latest show locale targets   # Available target languages

Buckets#

Buckets definem padrões de descoberta de arquivos e regras de processamento. Cada chave de bucket especifica um formato de arquivo, e seu valor determina quais arquivos incluir ou excluir:

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

Campo	Descrição
`include`	Array de padrões de arquivo com o placeholder `[locale]`. Suporta curingas glob (`*`).
`exclude`	Opcional. Array de padrões que devem ser ignorados durante o processamento.
`lockedKeys`	Opcional. Chaves cujos valores são copiados da origem sem tradução. Consulte Key Locking.
`ignoredKeys`	Opcional. Chaves totalmente excluídas da tradução — elas não aparecem nos arquivos de destino. Consulte Key Ignoring.
`preservedKeys`	Opcional. Chaves inicializadas uma única vez a partir da origem e depois protegidas contra atualizações automáticas. Consulte Key Preserving.
`injectLocale`	Opcional. Chaves em que o código do idioma de destino é inserido automaticamente.

Padrões de inclusão#

Os padrões de inclusão usam o placeholder [locale], que é resolvido para os códigos de idioma configurados em tempo de execução:

locales/[locale].json → locales/en.json, locales/es.json
docs/[locale]/*.md → docs/en/*.md, docs/es/*.md

Padrões glob recursivos (**/*.json) não são compatíveis. Em vez disso, use caminhos de diretório explícitos.

Delimitadores de idioma personalizados#

Por padrão, os códigos de idioma em nomes de arquivo usam hífen (-) como delimitador: en-US.json. Para usar underscores no lugar, passe um objeto com o campo delimiter:

json

{
  "include": [
    "standard/[locale].json",
    { "path": "legacy/[locale].json", "delimiter": "_" }
  ]
}

Isso gera legacy/en_US.json em vez de legacy/en-US.json.

Notação de caminho de chave#

Os arrays lockedKeys, ignoredKeys e preservedKeys usam barra (/) para indicar chaves aninhadas e asterisco (*) para curingas:

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

Para ver a lista completa de tipos de bucket compatíveis, consulte Supported Formats.

Provedor#

A seção provider configura um provedor LLM direto para tradução. Esta seção é opcional — quando omitida, o CLI usa um engine de localização na Lingo.dev.

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

Campo	Descrição
`provider.id`	Identificador do provedor: `openai`, `anthropic`, `google`, `mistral`, `openrouter` ou `ollama`.
`provider.model`	Nome do modelo no provedor (por exemplo, `gpt-4o-mini`, `claude-3-haiku`).
`provider.prompt`	Prompt de sistema. `{source}` e `{target}` são substituídos pelos códigos de idioma em tempo de execução.
`provider.baseUrl`	Opcional. Endpoint de API personalizado (obrigatório para Ollama: `http://localhost:11434`).

Conexão com o engine#

Para direcionar as traduções por um engine de localização específico, adicione o campo engineId:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Para o guia completo de configuração, consulte Connect Your Engine.

Variáveis de ambiente#

Variável	Obrigatório	Descrição
`LINGO_API_KEY`	Para o Lingo.dev Engine	Sua chave de API da Lingo.dev.
`LINGO_API_URL`	Não	URL base personalizada da API (para self-hosted ou staging).
`OPENAI_API_KEY`	Para o provedor OpenAI	Chave de API da OpenAI.
`ANTHROPIC_API_KEY`	Para o provedor Anthropic	Chave de API da Anthropic.
`GOOGLE_API_KEY`	Para o provedor Google	Chave de API do Google.
`MISTRAL_API_KEY`	Para o provedor Mistral	Chave de API da Mistral.
`OPENROUTER_API_KEY`	Para o provedor OpenRouter	Chave de API da OpenRouter.

Exemplo completo#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

Migração de versão#

Próximos passos#

Supported Formats

Todos os tipos de bucket e como configurá-los

i18n.lock

Como o lockfile acompanha o estado da tradução

Connect Your Engine

Direcione traduções pelo seu engine de localização

Setup

Instale o CLI e comece a usar