Pular para conteúdo

Início rápido

Crie um pequeno aplicativo com textos originais em inglês, traduções em português do Brasil, um seletor de idioma e mensagens com contexto e formas de plural.

1. Instale as ferramentas

Use Python 3.11 ou mais recente. Em um terminal, crie um projeto e instale os pacotes Python:

mkdir localized-app
cd localized-app
python -m venv .venv
source .venv/bin/activate
python -m pip install streamlit streamlit-gettext poethepoet

Estes comandos usam Bash no Linux ou macOS. No Windows, siga todo o guia dentro do WSL, incluindo a configuração do ambiente virtual, para que poe e as tarefas de shell usem o mesmo ambiente Linux.

Instale o GNU gettext separadamente; ele fornece xgettext e msgfmt. Por exemplo, no Ubuntu ou Debian:

sudo apt-get install gettext

No macOS com Homebrew:

brew install gettext

Para outros sistemas, consulte as instruções de instalação do GNU gettext. Execute os demais comandos em localized-app/, com o ambiente virtual ativado.

2. Crie o módulo de tradução

Salve o código abaixo como i18n.py, ao lado de app.py. Esse módulo pertence ao seu aplicativo; a biblioteca não o instala.

from pathlib import Path

from streamlit_gettext import GettextWrapper

wrapper = GettextWrapper(Path(__file__).parent / "locale")

gettext = wrapper.gettext
ngettext = wrapper.ngettext
pgettext = wrapper.pgettext
npgettext = wrapper.npgettext
get_available_languages = wrapper.get_available_languages
set_preferred_languages = wrapper.set_preferred_languages

O caminho do catálogo é relativo a i18n.py, portanto não depende do diretório de trabalho. O domínio padrão é messages, correspondente a messages.po e messages.mo.

3. Crie o aplicativo

Salve este código como app.py:

import streamlit as st
from i18n import (
    get_available_languages,
    ngettext,
    npgettext,
    pgettext,
    set_preferred_languages,
)
from i18n import gettext as _

language = st.selectbox(
    "Language",
    options=["auto", *get_available_languages()],
    format_func=lambda code: "Browser language" if code == "auto" else code,
)
set_preferred_languages(None if language == "auto" else [language])

st.title(_("File manager"))
count = st.slider(_("Number of files"), 1, 30, 1)
st.write(ngettext("%(num)d file", "%(num)d files", count) % {"num": count})

st.button(pgettext("action", "Open"))
st.write(pgettext("state", "Open"))
st.write(
    npgettext(
        "download",
        "Download %(num)d file",
        "Download %(num)d files",
        count,
    )
    % {"num": count}
)

gettext traduz uma mensagem. ngettext escolhe uma forma de plural. pgettext diferencia a ação “Open” do estado “Open” pelo argumento de contexto. npgettext combina contexto e seleção de plural.

Selecione auto para seguir o idioma do navegador, ou um código de idioma para substituí-lo. Passar None restaura a detecção pelo navegador. As preferências manuais são armazenadas separadamente para cada sessão do Streamlit. Os textos originais deste exemplo estão em inglês: assim, en usa as mensagens originais quando não há catálogo em inglês.

4. Extraia e traduza as mensagens

Crie pyproject.toml na raiz do projeto com estas tarefas, ou adicione a seção a um arquivo existente:

[tool.poe.tasks]
extract_pot = """
xgettext
    --keyword=pgettext:1c,2
    --keyword=npgettext:1c,2,3
    --no-location
    --output=locale/messages.pot
    app.py
"""

[tool.poe.tasks.update_po]
shell = """
find locale -type f -name '*.po' -exec sh -c '
    for po do
        msgmerge --update --backup=none "$po" locale/messages.pot || exit
    done
' sh {} +
"""

[tool.poe.tasks.compile_mo]
shell = """
find locale -type f -name '*.po' -exec sh -c '
    for po do
        msgfmt --check-format "$po" -o "${po%.po}.mo" || exit
    done
' sh {} +
"""

[tool.poe.tasks.init_po]
shell = """
mkdir -p "locale/${language}/LC_MESSAGES" &&
msginit --input=locale/messages.pot --output-file="locale/${language}/LC_MESSAGES/messages.po" --locale="${language}" --no-translator
"""
args = [{ name = "language", positional = true, required = true }]

Poe the Poet executa os comandos armazenados nesse arquivo. Você escreve as opções uma vez; depois, basta usar os nomes curtos das tarefas. O GNU gettext ainda precisa ser instalado separadamente.

xgettext identifica Python pela extensão .py, considera a codificação do código Python e reconhece _, gettext e ngettext por padrão. Chamadas com contexto exigem as opções adicionais --keyword.

Opções de extração:

Opção Finalidade
--keyword=pgettext:1c,2 O argumento 1 é o contexto (c); o argumento 2 é a mensagem.
--keyword=npgettext:1c,2,3 O argumento 1 é o contexto; os argumentos 2 e 3 são as mensagens no singular e no plural.
--no-location Omitir posições do código-fonte para reduzir alterações quando o código é movido.
--output=locale/messages.pot Gravar o modelo compartilhado de mensagens nesse arquivo.
app.py Arquivo-fonte a analisar; adicione outros arquivos à medida que o aplicativo crescer.

init_po recebe um argumento posicional obrigatório com o idioma. A tarefa cria locale/<language>/LC_MESSAGES e passa o idioma para msginit. Execute poe init_po pt_BR para português do Brasil ou poe init_po ja para japonês; não é necessário editar as tarefas ao adicionar idiomas.

update_po e compile_mo usam find para processar todos os arquivos .po em locale/. A primeira atualiza os catálogos a partir do modelo compartilhado sem arquivos de backup; a segunda verifica os marcadores de formatação e cria um .mo ao lado de cada .po. ${po%.po} remove o sufixo .po antes de adicionar .mo. for po do processa os caminhos passados por find, e || exit propaga falhas do gettext. Com -exec … +, find também retorna erro se um lote falhar, permitindo que Poe e CI detectem o problema. Os caminhos ficam entre aspas para aceitar diretórios com espaços.

Essas tarefas exigem um shell POSIX e find, disponíveis no Linux e macOS. No Windows, siga o guia dentro do WSL.

Crie o diretório comum dos catálogos e extraia as mensagens:

mkdir -p locale
poe extract_pot

Crie o arquivo .po a partir do modelo:

poe init_po pt_BR

Essa tarefa executa msginit: --input seleciona o modelo, --output-file o novo catálogo, --locale=pt_BR o idioma e --no-translator desativa perguntas interativas sobre o tradutor. O comando cria entradas com traduções vazias e inicializa o cabeçalho, incluindo Language e Plural-Forms.

Execute poe init_po <language> uma vez para cada novo idioma. As próximas execuções de poe update_po e poe compile_mo processam todos os idiomas adicionados em conjunto.

Você pode preencher as traduções com um editor especializado, como Poedit, que oferece uma interface para mensagens e formas de plural. Muitos serviços on-line, incluindo Crowdin e Transifex, oferecem suporte nativo a .po, sem conversão de formato.

É possível configurar uma integração com o repositório para enviar mensagens originais atualizadas e receber traduções prontas, por exemplo pela integração do Crowdin com GitHub ou pela integração do Transifex com GitHub. Depois de receber os .po atualizados, execute poe compile_mo para que o aplicativo use as novas traduções.

Abra locale/pt_BR/LC_MESSAGES/messages.po e preencha msgstr e msgstr[n]. No cabeçalho de metadados (msgid ""), defina UTF-8 como codificação e salve o arquivo nessa codificação:

"Content-Type: text/plain; charset=UTF-8\n"

Mantenha os demais campos gerados do cabeçalho, incluindo Plural-Forms. As entradas traduzidas devem ficar assim:

msgid "File manager"
msgstr "Gerenciador de arquivos"

msgid "Number of files"
msgstr "Número de arquivos"

#, python-format
msgid "%(num)d file"
msgid_plural "%(num)d files"
msgstr[0] "%(num)d arquivo"
msgstr[1] "%(num)d arquivos"

msgctxt "action"
msgid "Open"
msgstr "Abrir"

msgctxt "state"
msgid "Open"
msgstr "Aberto"

#, python-format
msgctxt "download"
msgid "Download %(num)d file"
msgid_plural "Download %(num)d files"
msgstr[0] "Baixar %(num)d arquivo"
msgstr[1] "Baixar %(num)d arquivos"

.pot é o modelo extraído, .po é a tradução editável e .mo é o catálogo compilado carregado pelo aplicativo. msgctxt deve corresponder ao contexto da chamada Python. Mantenha %(num)d sem alterações e traduza todas as formas de plural exigidas pelo idioma. O português do Brasil tem duas formas; outros idiomas podem exigir outra quantidade e outra expressão Plural-Forms.

5. Compile e execute

poe compile_mo

O projeto agora tem esta estrutura:

localized-app/
├── app.py
├── i18n.py
├── pyproject.toml
└── locale/
    ├── messages.pot
    └── pt_BR/
        └── LC_MESSAGES/
            ├── messages.po
            └── messages.mo

Inicie o aplicativo:

python -m streamlit run app.py

Selecione pt_BR: o título deve mudar para “Gerenciador de arquivos”. Ajuste o controle deslizante para 1, 2 e 5 para ver “1 arquivo”, “2 arquivos” e “5 arquivos”. O botão mostra “Abrir”, enquanto o estado mostra “Aberto”. Selecione en para voltar ao texto original em inglês, ou auto para usar o idioma do navegador.

Se uma mensagem continuar em inglês, confira o idioma selecionado, a localização do catálogo, o domínio e se o .mo foi recompilado após editar o .po. msgfmt ignora entradas marcadas como fuzzy: revise a tradução e remova a marca antes de compilar. Reinicie o Streamlit após recompilar os catálogos para limpar as traduções em cache.

Mantenha as traduções atualizadas

Depois de alterar as mensagens originais, extraia-as novamente e atualize os catálogos:

poe extract_pot
poe update_po

Traduza as entradas novas ou alteradas, revise as marcas fuzzy, execute poe compile_mo e reinicie o aplicativo. Consulte o fluxo de tradução para as tarefas do exemplo do repositório, ou a referência da API para as interfaces da biblioteca.