Configuração do i18n.json

i18n.json é o ficheiro de configuração que controla o CLI da Lingo.dev e as integrações de CI/CD. Define que idiomas traduzir, onde está o conteúdo traduzível e que 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 ativa o preenchimento automático e a validação no IDE. O campo version regista a versão do esquema para garantir compatibilidade com migrações automáticas.

Idioma#

A secçã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 o conteúdo de origem está escrito. Todas as traduções partem deste idioma.
`locale.targets`	Array de idiomas de destino. Cada idioma de destino gera um ficheiro separado (ou secção), consoante o formato do bucket.

Os códigos de idioma seguem a norma BCP 47 — en, en-US, es-ES, zh-Hans e formatos específicos de plataformas, como o en-rUS do Android, são todos suportados.

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#

Os buckets definem padrões de deteção de ficheiros e regras de processamento. Cada chave de bucket especifica um formato de ficheiro, e o respetivo valor configura que ficheiros 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 ficheiros com o placeholder `[locale]`. Suporta wildcards glob (`*`).
`exclude`	Opcional. Array de padrões a ignorar 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 — não aparecem nos ficheiros 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 é injetado 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

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

Delimitadores de idioma personalizados#

Por predefinição, os códigos de idioma nos nomes dos ficheiros usam o hífen (-) como delimitador: en-US.json. Para usar underscores em vez disso, passe um objeto com um campo delimiter:

json

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

Isto 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 a barra (/) para chaves aninhadas e o asterisco (*) para wildcards:

json

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

Para ver a lista completa de tipos de bucket suportados, consulte Supported Formats.

Fornecedor#

A secção provider configura um fornecedor de LLM direto para tradução. Esta secção é opcional — se for omitida, o CLI usa um motor 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 fornecedor: `openai`, `anthropic`, `google`, `mistral`, `openrouter` ou `ollama`.
`provider.model`	Nome do modelo do fornecedor (por exemplo, `gpt-4o-mini`, `claude-3-haiku`).
`provider.prompt`	Prompt de sistema. `{source}` e `{target}` são substituídos por códigos de idioma em tempo de execução.
`provider.baseUrl`	Opcional. Endpoint de API personalizado (obrigatório para Ollama: `http://localhost:11434`).

Ligação ao motor#

Para encaminhar as traduções através de um motor de localização específico, adicione o campo engineId:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

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

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

Variáveis de ambiente#

Variável	Obrigatório	Descrição
`LINGO_API_KEY`	Para o motor da Lingo.dev	A sua chave de API da Lingo.dev.
`LINGO_API_URL`	Não	URL base da API personalizada (para ambientes self-hosted ou de staging).
`OPENAI_API_KEY`	Para o fornecedor OpenAI	Chave da API da OpenAI.
`ANTHROPIC_API_KEY`	Para o fornecedor Anthropic	Chave da API da Anthropic.
`GOOGLE_API_KEY`	Para o fornecedor Google	Chave da API da Google.
`MISTRAL_API_KEY`	Para o fornecedor Mistral	Chave da API da Mistral.
`OPENROUTER_API_KEY`	Para o fornecedor OpenRouter	Chave da 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 i18n.json antigas para a versão mais recente do esquema. Cria uma cópia de segurança do ficheiro atual, atualiza o esquema e preserva todas as definições. Não é necessária qualquer intervenção manual.

Próximos passos#

Supported Formats

Todos os tipos de bucket e respetiva configuração

i18n.lock

Como o ficheiro lock acompanha o estado da tradução

Connect Your Engine

Encaminhe as traduções através do seu motor de localização

Setup

Instale o CLI e dê os primeiros passos

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 ativa o preenchimento automático e a validação no IDE. O campo version regista a versão do esquema para garantir compatibilidade com migrações automáticas.

Idioma#

A secçã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 o conteúdo de origem está escrito. Todas as traduções partem deste idioma.
`locale.targets`	Array de idiomas de destino. Cada idioma de destino gera um ficheiro separado (ou secção), consoante o formato do bucket.

Os códigos de idioma seguem a norma BCP 47 — en, en-US, es-ES, zh-Hans e formatos específicos de plataformas, como o en-rUS do Android, são todos suportados.

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#

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 ficheiros com o placeholder `[locale]`. Suporta wildcards glob (`*`).
`exclude`	Opcional. Array de padrões a ignorar 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 — não aparecem nos ficheiros 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 é injetado 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

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

Delimitadores de idioma personalizados#

Por predefinição, os códigos de idioma nos nomes dos ficheiros usam o hífen (-) como delimitador: en-US.json. Para usar underscores em vez disso, passe um objeto com um campo delimiter:

json

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

Isto 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 a barra (/) para chaves aninhadas e o asterisco (*) para wildcards:

json

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

Para ver a lista completa de tipos de bucket suportados, consulte Supported Formats.

Fornecedor#

A secção provider configura um fornecedor de LLM direto para tradução. Esta secção é opcional — se for omitida, o CLI usa um motor 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 fornecedor: `openai`, `anthropic`, `google`, `mistral`, `openrouter` ou `ollama`.
`provider.model`	Nome do modelo do fornecedor (por exemplo, `gpt-4o-mini`, `claude-3-haiku`).
`provider.prompt`	Prompt de sistema. `{source}` e `{target}` são substituídos por códigos de idioma em tempo de execução.
`provider.baseUrl`	Opcional. Endpoint de API personalizado (obrigatório para Ollama: `http://localhost:11434`).

Ligação ao motor#

Para encaminhar as traduções através de um motor de localização específico, adicione o campo engineId:

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

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

Variáveis de ambiente#

Variável	Obrigatório	Descrição
`LINGO_API_KEY`	Para o motor da Lingo.dev	A sua chave de API da Lingo.dev.
`LINGO_API_URL`	Não	URL base da API personalizada (para ambientes self-hosted ou de staging).
`OPENAI_API_KEY`	Para o fornecedor OpenAI	Chave da API da OpenAI.
`ANTHROPIC_API_KEY`	Para o fornecedor Anthropic	Chave da API da Anthropic.
`GOOGLE_API_KEY`	Para o fornecedor Google	Chave da API da Google.
`MISTRAL_API_KEY`	Para o fornecedor Mistral	Chave da API da Mistral.
`OPENROUTER_API_KEY`	Para o fornecedor OpenRouter	Chave da 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 respetiva configuração

i18n.lock

Como o ficheiro lock acompanha o estado da tradução

Connect Your Engine

Encaminhe as traduções através do seu motor de localização

Setup

Instale o CLI e dê os primeiros passos