Skip to content

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:

ts
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:

ts
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çãoDescrição
loadI18nConfigFromFileCarrega, mescla e valida a configuração a partir de um arquivo JSON.
parseI18nConfigValida um objeto de configuração bruto.
TranslationCacheCache SQLite - instanciar com um caminho cacheDir.
UIStringExtractorExtrair strings t("…") do código-fonte JS/TS.
collectHtmlI18nStrings / markHtmlContentEscaneia / insere marcadores data-i18n* em HTML (alimenta extract para .html e o comando mark-html).
MarkdownExtractorExtrair segmentos traduzíveis do markdown.
HtmlTemplateExtractorExtrair e remontar documentos HTML simples (texto e atributos traduzíveis; src / href permanecem no lugar).
JsonExtractorExtrair de arquivos de rótulo JSON do Docusaurus (catálogos de interface, não corpo MDX).
SvgExtractorExtrair de arquivos SVG.
LlmClientFaz solicitações de tradução para o provedor LLM ativo (OpenRouterClient é um alias obsoleto).
rankProviderModels / resolveSuggestionWeightsClassifica 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.
PlaceholderHandlerProtege/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 / restoreMdxProtege/restaura comentários MDX, tags JSX, expressões entre chaves e atributos de string JSX (chamado por PlaceholderHandler; também exportado para uso direto).
splitTranslatableIntoBatchesAgrupar segmentos em lotes com tamanho adequado para LLMs.
validateTranslationVerificações estruturais após a tradução (assíncronas — devem ser aguardadas).
resolveDocumentationOutputPathResolver o caminho do arquivo de saída para um documento traduzido.
Glossary / GlossaryMatcherCarrega e aplica glossários de tradução, incluindo notas opcionais de Context de termos.
loadTranslationContext / computeGuidanceFingerprintCarrega glossary.contextFiles e orientação de impressão digital para invalidação de cache.
runTranslateUIPonto de entrada programático para translate-ui.
writeInitConfigFileGrava um JSON de configuração inicial (template, cwd, um providerKey obrigatório e um { withReadme } opcional). Retorna { readmeBlockAdded, hasReadmeBlock }.
DEFAULT_INIT_MODELS_BY_PROVIDERtranslationModels inicial por preset integrado usado por init -P.
PROVIDER_PRESETSMapa 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çãoComportamento
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.

MembroComportamento
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.
SupportedLocalesBuiltInLocales 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.

Lançado sob a Licença MIT.