Skip to main content

i18n em Python: o guia completo da localização

Configure python-i18n com arquivos JSON ou YAML, trate marcadores e plurais e automatize traduções com IA.

1

Instalar python-i18n

python-i18n é uma biblioteca leve de internacionalização para Python. Aceita nativamente arquivos JSON e YAML, chaves aninhadas, interpolação de marcadores e pluralização.

Terminal
pip install python-i18n
python-i18n aceita JSON por padrão. Para arquivos YAML, instale a dependência opcional com pip install python-i18n[YAML], que adiciona PyYAML.
Terminal
# To use YAML translation files instead of JSON:
pip install python-i18n[YAML]
2

Configurar traduções

Defina o formato, adicione caminhos dos arquivos e configure as localidades predefinida e de fallback. Importe esta configuração no ponto de entrada da aplicação antes de qualquer chamada de tradução.

i18n_config.py
import i18n

# Set the file format (json or yaml)
i18n.set("file_format", "json")

# Add the directory containing your translation files
i18n.load_path.append("translations/")

# Set the default locale
i18n.set("locale", "en")

# Set the fallback locale (used when a key is missing)
i18n.set("fallback", "en")

# Enable/disable error on missing translations
i18n.set("error_on_missing_translation", False)
load_path deve apontar para o diretório que contém os arquivos, não para um arquivo específico. Se as traduções devolverem chaves em bruto, verifique se load_path está correto e se os nomes correspondem aos códigos regionais —por exemplo, en.json e de.json—.
3

Criar arquivos de tradução

Crie um arquivo por idioma em JSON ou YAML. Utilize chaves aninhadas para organizar strings por funcionalidade ou página. Mantenha o idioma de origem —normalmente inglês— como única fonte de referência.

translations/en.json
// translations/en.json
{
  "greeting": "Hello!",
  "welcome": "Welcome to our application",
  "nav": {
    "home": "Home",
    "about": "About",
    "settings": "Settings"
  },
  "cart": {
    "item_count": "%{count} item(s) in your cart"
  }
}

// translations/de.json
{
  "greeting": "Hallo!",
  "welcome": "Willkommen in unserer Anwendung",
  "nav": {
    "home": "Startseite",
    "about": "Über uns",
    "settings": "Einstellungen"
  },
  "cart": {
    "item_count": "%{count} Artikel in Ihrem Warenkorb"
  }
}
Dê às chaves nomes que descrevam o conteúdo, não o local onde aparece: 'cart.item_count' é melhor do que 'homepage_cart_label'. As chaves devem sobreviver a alterações na interface.
4

Utilizar traduções no código

Chame i18n.t() com um caminho de chave separado por pontos para obter strings traduzidas. Pode substituir a localidade em cada chamada sem alterar a definição global.

app.py
import i18n

# Simple translation
print(i18n.t("greeting"))          # "Hello!"
print(i18n.t("nav.home"))          # "Home"
print(i18n.t("nav.about"))         # "About"

# Translation with a specific locale
print(i18n.t("greeting", locale="de"))   # "Hallo!"
print(i18n.t("nav.home", locale="ja"))   # "ホーム"

# Missing key returns a placeholder
print(i18n.t("missing.key"))       # "Missing.Key"
As chaves aninhadas utilizam notação por pontos: i18n.t('nav.home'). Se as chaves JSON contiverem pontos literais, python-i18n os interpreta como separadores de aninhamento. Evite pontos nos nomes.
5

Marcadores e pluralização

python-i18n aceita interpolação de marcadores com a sintaxe %{name} e pluralização básica através das subchaves 'zero', 'one' e 'many'. Passe argumentos por palavra-chave a i18n.t() em ambas.

Placeholders
# translations/en.json
# {
#   "welcome_user": "Welcome, %{name}!",
#   "order_status": "Order #%{order_id}: %{status}",
#   "file_size": "File size: %{size} %{unit}"
# }

import i18n

# Single placeholder
print(i18n.t("welcome_user", name="Alice"))
# "Welcome, Alice!"

# Multiple placeholders
print(i18n.t("order_status", order_id=12345, status="shipped"))
# "Order #12345: shipped"

# Reusable with different values
print(i18n.t("file_size", size=2.5, unit="MB"))
# "File size: 2.5 MB"

print(i18n.t("file_size", size=800, unit="KB"))
# "File size: 800 KB"
Pluralization
# translations/en.json
# {
#   "inbox": {
#     "zero": "No messages",
#     "one": "1 message",
#     "many": "%{count} messages"
#   }
# }

import i18n

print(i18n.t("inbox", count=0))    # "No messages"
print(i18n.t("inbox", count=1))    # "1 message"
print(i18n.t("inbox", count=42))   # "42 messages"
A pluralização de python-i18n utiliza três categorias: zero, one e many. Abrange inglês e muitos outros idiomas, mas não todas as regras CLDR —few, two e other—. Em idiomas complexos, como árabe, russo ou polonês, talvez tenha de tratar casos-limite manualmente ou utilizar uma biblioteca mais avançada.
6

Mudar de localidade durante a execução

Mude globalmente a localidade ativa com i18n.set('locale', code) ou em cada chamada através do argumento locale. Nos frameworks Web, detecte o idioma preferido a partir da requisição e defina a localidade antes de apresentar.

Locale switching
import i18n

# Set locale globally
i18n.set("locale", "de")
print(i18n.t("greeting"))           # "Hallo!"

# Switch to Japanese
i18n.set("locale", "ja")
print(i18n.t("greeting"))           # "こんにちは！"

# Override per-call without changing global locale
i18n.set("locale", "en")
print(i18n.t("greeting"))           # "Hello!"
print(i18n.t("greeting", locale="de"))  # "Hallo!"
app.py
from flask import Flask, request, g
import i18n

app = Flask(__name__)

i18n.set("file_format", "json")
i18n.load_path.append("translations/")

SUPPORTED_LOCALES = ["en", "de", "ja", "es", "fr"]

@app.before_request
def set_locale():
    # Check URL parameter, cookie, then Accept-Language header
    locale = request.args.get("lang")
    if not locale:
        locale = request.cookies.get("locale")
    if not locale:
        locale = request.accept_languages.best_match(SUPPORTED_LOCALES)
    g.locale = locale or "en"
    i18n.set("locale", g.locale)

@app.route("/")
def index():
    return i18n.t("welcome")
i18n.set('locale', ...) altera globalmente a localidade. Nos servidores Web com várias threads —gunicorn com workers ou Django—, isto pode criar condições de corrida em que uma requisição muda a localidade enquanto outra está sendo apresentada. Utilize substituições por chamada ou armazenamento local da thread.
7

Fallback regional inteligente com python-i18n-locale-chain

Por padrão, python-i18n só aceita uma localidade de fallback. Se um usuário pt-BR não tiver traduções pt-BR, a biblioteca passa diretamente para inglês e ignora pt-PT. python-i18n-locale-chain corrige isto com cadeias configuráveis para 75 variantes.

python-i18n-locale-chain é um pacote gratuito e de código aberto. Uma chamada ativa 75 cadeias integradas para variantes de chinês, português, espanhol, francês, alemão, italiano, holandês, inglês, árabe, norueguês e malaio.
Terminal
pip install python-i18n-locale-chain
i18n_config.py
from locale_chain import configure
import i18n

i18n.set("file_format", "json")
i18n.load_path.append("translations/")

# Activate smart fallback chains (75 built-in chains)
configure()

# Now pt-BR falls back to pt-PT -> pt -> en (instead of just en)
result = i18n.t("greeting", locale="pt-BR")

# es-MX falls back to es-419 -> es -> en
result = i18n.t("greeting", locale="es-MX")

# zh-Hant-HK falls back to zh-Hant-TW -> zh-Hant -> en
result = i18n.t("greeting", locale="zh-Hant-HK")
Advanced configuration
from locale_chain import configure, reset

# Override specific chains
configure(overrides={
    "pt-BR": ["pt"],         # Skip pt-PT, go straight to pt
    "ja-JP": ["ja"],         # Add a new chain
})

# Full custom map (no defaults)
configure(
    fallbacks={"pt-BR": ["pt-PT"]},
    merge_defaults=False
)

# Use German as final fallback instead of English
configure(default_locale="de")

# Restore original i18n.t() behaviour
reset()
As cadeias mais importantes a testar: pt-BR -> pt-PT -> pt -> en —português—, es-MX -> es-419 -> es -> en —espanhol— e zh-Hant-HK -> zh-Hant-TW -> zh-Hant -> en —chinês tradicional—. Abrangem os cenários regionais mais frequentes.
8

Automatizar as traduções

Depois de concluir a configuração de i18n, traduza os arquivos de localidade com IA. No IDE, peça ao assistente para traduzir o arquivo de origem ou utilize a CLI do i18n Agent no seu pipeline de CI/CD.

Terminal
# In your IDE, ask your AI assistant:
> Translate translations/en.json to German, Japanese, and Spanish

translations/de.json created (1.2s)
translations/ja.json created (1.5s)
translations/es.json created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate translations/en.json --lang de,ja,es
Traduza de forma incremental. Quando adicionar chaves ao arquivo de origem, traduza apenas as diferenças em vez de voltar a gerar tudo. Assim preserva traduções revisadas por pessoas.

Automatizar a qualidade das traduções

Detecte chaves em falta e marcadores danificados antes da publicação com i18n-validate. Teste a interface com pseudotraduções através de i18n-pseudo antes de chegarem as traduções reais.

Erros frequentes

As traduções devolvem chaves em bruto

Causas: load_path não foi definido ou aponta para o diretório errado; file_format não corresponde às extensões; ou os nomes não correspondem aos códigos regionais. Confirme se i18n.load_path contém o diretório correto e se os arquivos se chamam, por exemplo, en.json e de.json.

Os arquivos YAML não carregam

python-i18n exige PyYAML para aceitar YAML, mas não o instala por padrão. Instale com pip install python-i18n[YAML]. Sem este pacote, os arquivos são ignorados silenciosamente e as traduções devolvem marcadores de chaves em falta.

Falham as pesquisas de chaves aninhadas

python-i18n utiliza notação por pontos nas chaves aninhadas: i18n.t('nav.home'). Se o JSON utilizar chaves simples com pontos no nome —'nav.home' como uma só chave—, a biblioteca as interpreta como pesquisa aninhada e falha. Utilize objetos JSON realmente aninhados.

As mudanças de localidade se propagam entre requisições

i18n.set('locale', ...) é uma operação global. Em servidores com várias threads, uma requisição pode mudar a localidade enquanto outra é apresentada. Utilize o argumento locale= em cada chamada i18n.t() ou defina a localidade no armazenamento local da thread através de middleware.

Estrutura de arquivos recomendada

Project Structure
my-python-app/
├── translations/
│   ├── en.json           # Source language (JSON)
│   ├── de.json           # German
│   ├── ja.json           # Japanese
│   ├── es.json           # Spanish
│   └── pt-BR.json        # Brazilian Portuguese
├── app.py                # Application entry point
├── i18n_config.py        # i18n setup and configuration
├── requirements.txt      # pip dependencies
└── pyproject.toml        # Project metadata

# Or with YAML files:
my-python-app/
├── translations/
│   ├── en.yml
│   ├── de.yml
│   └── ja.yml
├── app.py
└── ...

Também pode traduzir:

Experimente já o i18n Agent

Solte aqui seu arquivo de tradução

JSON, YAML, PO, XML, CSV, Markdown, Properties

ou clique para selecionar

Idiomas de destino

Sem cadastroEstimativa imediata

Fallback regional com python-i18n-locale-chain

Quando falta uma chave em uma localidade como es-419, python-i18n passa diretamente para a localidade predefinida em vez de verificar primeiro a localidade principal es.

Terminal
pip install python-i18n-locale-chain
Configuration
from i18n_locale_chain import configure_chain

configure_chain('{')
    'es': ['en', 'ru'],
    'pt-BR': ['pt', 'en'],
    'zh-Hant-HK': ['zh-Hant', 'zh', 'en'],
'}')

# Utilização: t('greeting', locale='es') — recorre à cadeia

Consulte nosso guia de fallback regional para ver a lista completa de frameworks compatíveis e as 75 cadeias integradas. Learn more →

Perguntas frequentes