API Programática
Todos os tipos e classes públicos são exportados da raiz do pacote. Exemplo: executar a etapa translate-ui a partir do Node.js sem a CLI:
import { loadI18nConfigFromFile, runTranslateUI } from 'ai-i18n-tools';
// Config must have features.translateUIStrings: true (and valid targetLocales, etc.).
const config = loadI18nConfigFromFile('ai-i18n-tools.config.json');
const summary = await runTranslateUI(config, {
cwd: process.cwd(),
locales: config.targetLocales,
force: false,
dryRun: false,
verbose: false,
});
console.log(
`Updated ${summary.stringsUpdated} string(s); locales touched: ${summary.localesTouched.join(', ')}`
);Crie a estrutura de uma configuração a partir do Node.js. O quarto argumento é a predefinição integrada (cwd é o terceiro). Um quinto argumento opcional { withReadme: true } anexa o bloco de documentação README simples quando o modelo não lista README.md e retorna se esse bloco foi adicionado:
import { writeInitConfigFile } from 'ai-i18n-tools';
writeInitConfigFile('ai-i18n-tools.config.json', 'uiMarkdown', process.cwd(), 'anthropic');
writeInitConfigFile('ai-i18n-tools.config.json', 'docsMarkdown', process.cwd(), 'openrouter');
writeInitConfigFile('ai-i18n-tools.config.json', 'uiPython', process.cwd(), 'openrouter', {
withReadme: true,
});Exportações principais (comumente usadas — consulte src/index.ts para a superfície pública completa):
| Exportação | Descrição |
|---|---|
loadI18nConfigFromFile | Carrega, mescla e valida a configuração a partir de um arquivo JSON. |
parseI18nConfig | Valida um objeto de configuração bruto. |
TranslationCache | Cache SQLite - instanciar com um caminho cacheDir. |
UIStringExtractor | Extrair strings t("…") do código-fonte JS/TS. |
collectHtmlI18nStrings / markHtmlContent | Escaneia / insere marcadores data-i18n* em HTML (alimenta extract para .html e o comando mark-html). |
MarkdownExtractor | Extrair segmentos traduzíveis do markdown. |
HtmlTemplateExtractor | Extrair e remontar documentos HTML simples (texto e atributos traduzíveis; src / href permanecem no lugar). |
JsonExtractor | Extrair de arquivos de rótulo JSON do Docusaurus (catálogos de interface, não corpo MDX). |
SvgExtractor | Extrair de arquivos SVG. |
LlmClient | Faz solicitações de tradução para o provedor LLM ativo (OpenRouterClient é um alias obsoleto). |
rankProviderModels / resolveSuggestionWeights | Classifica o catálogo de chat de um provedor. O índice é ChrF e Arena; o perfil de qualidade classifica por esse índice, e o perfil de preço percorre a fronteira de Pareto. Não imprime nem escreve a configuração. |
PlaceholderHandler | Protege/restaura a sintaxe markdown ao redor da tradução (tags HTML, advertências, âncoras, comentários MDX/JSX/chaves, URLs, código embutido, ênfase). |
protectMdx / restoreMdx | Protege/restaura comentários MDX, tags JSX, expressões entre chaves e atributos de string JSX (chamado por PlaceholderHandler; também exportado para uso direto). |
splitTranslatableIntoBatches | Agrupar segmentos em lotes com tamanho adequado para LLMs. |
validateTranslation | Verificações estruturais após a tradução (assíncronas — devem ser aguardadas). |
resolveDocumentationOutputPath | Resolver o caminho do arquivo de saída para um documento traduzido. |
Glossary / GlossaryMatcher | Carrega e aplica glossários de tradução, incluindo notas opcionais de Context de termos. |
loadTranslationContext / computeGuidanceFingerprint | Carrega glossary.contextFiles e orientação de impressão digital para invalidação de cache. |
runTranslateUI | Ponto de entrada programático para translate-ui. |
writeInitConfigFile | Grava um JSON de configuração inicial (template, cwd, um providerKey obrigatório e um { withReadme } opcional). Retorna { readmeBlockAdded, hasReadmeBlock }. |
DEFAULT_INIT_MODELS_BY_PROVIDER | translationModels inicial por preset integrado usado por init -P. |
PROVIDER_PRESETS | Mapa predefinido de provedor integrado (baseUrl, apiKeyEnv). |
Ambiente de execução do Python (i18n.py)
init -t ui-python, ui-python-gettext e ui-python-flask gravam este módulo no projeto quando i18n.py está ausente. É um auxiliar da biblioteca padrão para Python 3.10 ou superior. Importe-o a partir desse arquivo. As funções abaixo são separadas das exportações do Node na tabela acima. Projetos Django mantêm o gettext do Django, portanto ui-python-django não grava i18n.py.
Formatos de chamada, f-strings inseguras e configuração de localidade por framework: Aplicações Python.
| Função | Comportamento |
|---|---|
set_locale(locale) | Define a localidade atual. Sublinhados no código são armazenados como hifens (pt_BR torna-se pt-BR). Retorna um token ContextVar. |
reset_locale(token) | Restaura a localidade a partir desse token. Chame-a em finally, incluindo middleware de FastAPI e Flask. |
get_locale() | Retorna a localidade atual. |
set_backend(backend) | Seleciona "auto", "json" ou "gettext". |
get_ui_languages() | Lê ui-languages.json próximo ao diretório JSON simples, ou o diretório gettext quando a saída simples está desativada. |
get_direction(locale=None) | Retorna "rtl" ou "ltr" da linha do manifesto para essa localidade (localidade atual quando omitido). |
_(message) | Procura um literal e, em seguida, retorna a string do catálogo ou a própria mensagem. |
t(template, *, plurals=False, count=None, **values) | Procura o literal e, em seguida, interpola. translate é a mesma função. No Python 3.14, translate(t"Hello, {name}!") mantém o modelo e seus valores. Argumentos nomeados substituem valores obtidos de uma string de modelo. |
ngettext(singular, plural, n, **values) | Procura plural e, em seguida, interpola. count está disponível para a string de formato. |
pgettext(context, message, **values) | Consulta de contexto (msgctxt ou context + U+0004 + a string do idioma de origem em JSON simples), depois interpola. |
streamlit_language_selector(sidebar=True, key="lang_selector") | Caixa de seleção do Streamlit. Grava st.session_state.locale e st.query_params["lang"], chama set_locale e retorna o código escolhido. |
Runtime do .NET (I18n.cs)
init -t ui-dotnet copia assets/dotnet/I18n.cs para o projeto quando I18n.cs está ausente. É um auxiliar sem dependências para .NET 6 ou mais recente. Os membros abaixo são separados das exportações do Node na tabela acima. Formatos de chamada e marcação XAML: aplicativos .NET.
| Membro | Comportamento |
|---|---|
SetLocale(locale) | Carrega o JSON plano dessa localidade, percorrendo CultureInfo.Parent quando o arquivo exato está ausente. Gera LocaleChanged. |
T(source, args) | Procura o literal aparado, formata com string.Format e restaura os espaços em branco iniciais e finais da origem. |
Tn(singular, plural, count, args) | Consulta de plural. {0} é a contagem. A chave do catálogo é o MD5-8 do singular aparado mais _ e o formato CLDR. |
Tp(context, source, args) | Procura contexto + U+0004 + origem, então formata. |
N(source) | Retorna source. Extraído para que rótulos estáticos possam ser catalogados. |
Loc[source] | Indexador que chama T. Loc é um campo estático do tipo StringSourceLocalizer. |
Configure(options) | Define o local de origem quando SourceLocale não está vazio. Cada chamada substitui Strict, FlatDirectory e OpenLocale (nulo limpa o diretório e o carregador de fluxo). Locales substitui a lista de idiomas somente quando o array não é nulo. |
SupportedLocales | BuiltInLocales até que um array Locales não nulo seja passado. Nome nativo e nome em inglês. Um array Locales nulo não restaura o carimbo. |
IsRightToLeft(locale) | CultureInfo.TextInfo.IsRightToLeft. |
PluralForm(locale, n) | Nome do formato CLDR das mesmas regras GNU que os arquivos .po. |
init -t ui-dotnet-resx copia I18nResx.cs em vez disso. T, Tn e Tp chamam ResourceManager com as mesmas chaves de string de origem. SetLocale define CurrentUICulture e CurrentCulture. Detalhes: Adicionar i18n a um aplicativo ResourceManager .NET.