Auxiliares de tempo de execução

Esses auxiliares são exportados de 'ai-i18n-tools/runtime' e funcionam em qualquer ambiente JavaScript (navegador, Node.js, Deno, Edge). Eles não importam de i18next ou react-i18next.

Use-os na inicialização do seu aplicativo (src/i18n.js), no seletor de idioma e em qualquer código não-React que precise de utilitários de direção ou string. Para conexão de ponta a ponta, comece com Conectar i18next; para menus de idioma e RTL, consulte Seletor de idioma e RTL.

Padrões de importação

A exportação padrão é apenas o namespace i18next-helper (defaultI18nInitOptions, setupKeyAsDefaultT, wrapT, makeLoadLocale, …). Importe interpolateTemplate, flipUiArrowsForRtl, auxiliares de exibição e tipos como exportações nomeadas — eles não são propriedades na exportação padrão.

// Namespace style (common in i18n bootstrap files)
import aiI18n from 'ai-i18n-tools/runtime';
aiI18n.setupKeyAsDefaultT(i18n, { stringsJson });

// Named imports (language switcher, one-off utilities)
import {
  getUILanguageLabel,
  getTextDirection,
  type UiLanguageManifestRow,
} from 'ai-i18n-tools/runtime';

Bootstrap típico

Um src/i18n.ts mínimo compõe os helpers do i18next. SOURCE_LOCALE deve corresponder a sourceLocale em ai-i18n-tools.config.json. Os caminhos de importação abaixo assumem que este arquivo está ao lado de locales/.

import i18n from 'i18next';
import aiI18n from 'ai-i18n-tools/runtime';
import stringsJson from './locales/strings.json';
import uiLanguages from './locales/ui-languages.json';

export const SOURCE_LOCALE = 'en-GB';

void i18n.init(aiI18n.defaultI18nInitOptions(SOURCE_LOCALE));
aiI18n.setupKeyAsDefaultT(i18n, {
  stringsJson,
});

const localeLoaders = aiI18n.makeLocaleLoadersFromManifest(
  uiLanguages,
  SOURCE_LOCALE,
  (code) => () => import(`./locales/${code}.json`),
);

export const loadLocale = aiI18n.makeLoadLocale(i18n, localeLoaders, SOURCE_LOCALE);
export const t = i18n.t.bind(i18n);
export default i18n;

Ao alterar o idioma, chame await loadLocale(next) e depois await i18n.changeLanguage(next). React (initReactI18next), plurais do locale de origem (sourcePluralFlatBundle) e applyDirection são abordados em Integrar o i18next.

Referência rápida

Exportação	Função
defaultI18nInitOptions(sourceLocale?)	Opções padrão de i18next init() para configurações de chave como padrão.
setupKeyAsDefaultT(i18n, options)	Ponto de entrada de aplicativo recomendado — wrapper de corte de chave, pacote plural de origem opcional, wrapT com reconhecimento de plural.
wrapT(i18n, options)	Wrapper de t() plural de nível inferior (geralmente instalado por setupKeyAsDefaultT).
buildPluralIndexFromStringsJson(entries)	Constrói o mapa literal → groupId que wrapT usa a partir de linhas strings.json com "plural": true.
extractInterpolationNamesForWrap(message)	Analisa nomes de placeholders {{var}} de uma string de origem.
wrapI18nWithKeyTrim(i18n)	Apenas fallback de {{var}} de localidade de origem + key-trim. Obsoleto para conexão de aplicativo — use setupKeyAsDefaultT.
makeLocaleLoadersFromManifest(manifest, sourceLocale, makeLoader)	Constrói o mapa localeLoaders para makeLoadLocale a partir de ui-languages.json (cada code exceto sourceLocale).
makeLoadLocale(i18n, loaders, sourceLocale?)	Fábrica para carregamento assíncrono de JSON de localidade via addResourceBundle.
RTL_LANGS	Conjunto somente leitura de códigos de idioma base RTL (fallback quando uma localidade está faltando no catálogo empacotado).
getTextDirection(lng)	Retorna 'ltr' ou 'rtl' para um código BCP-47.
applyDirection(lng, element?)	Define o atributo dir em document.documentElement (navegador) ou em um elemento personalizado.
getUILanguageLabel(lang, t)	Rótulo do menu de idioma usando t(englishName) quando traduzido.
getUILanguageLabelNative(lang)	Rótulo do menu de idioma apenas dos campos do manifesto (englishName / label).
interpolateTemplate(str, vars)	Substituição de {{var}} de baixo nível em uma string simples (prefira t() em React/i18next).
flipUiArrowsForRtl(text, isRtl)	Inverte → para ← em layouts da direita para a esquerda (RTL).

Auxiliares de RTL

RTL_LANGS: ReadonlySet<string>
getTextDirection(lng: string): 'ltr' | 'rtl'
applyDirection(lng: string, element?: { setAttribute(name: string, value: string): void }): void

getTextDirection consulta primeiro o catálogo data/ui-languages-complete.json empacotado (mesma fonte que generate-ui-languages), depois retorna para RTL_LANGS para códigos não presentes no catálogo.

applyDirection é seguro no Node.js — ele não faz nada quando document não está disponível. No navegador, omita element para atualizar document.documentElement. Conecte-o na mudança de idioma: i18n.on('languageChanged', applyDirection).

Fábricas de configuração do i18next

defaultI18nInitOptions(sourceLocale?: string): {
  resources: Record<string, never>;
  lng: string;
  fallbackLng: string;
  parseMissingKeyHandler: (key: string) => string;
  interpolation: { escapeValue: false };
  nsSeparator: false;
}

setupKeyAsDefaultT(
  i18n: I18nLike & Partial<Pick<I18nWithResources, 'addResourceBundle'>>,
  options: SetupKeyAsDefaultTOptions
): void

// SetupKeyAsDefaultTOptions:
// {
//   stringsJson: Record<string, { plural?: boolean; source?: string }>;
//   sourcePluralFlatBundle?: { lng: string; bundle: Record<string, string> };
// }

wrapI18nWithKeyTrim(i18n: I18nLike): void
wrapT(i18n: I18nLike, options: WrapTOptions): void
// WrapTOptions: { pluralIndex: Record<string, string> }

buildPluralIndexFromStringsJson(
  entries: Record<string, { plural?: boolean; source?: string }>
): Record<string, string>

extractInterpolationNamesForWrap(message: string): string[]

makeLocaleLoadersFromManifest(
  manifest: readonly { code: string }[],
  sourceLocale: string,
  makeLoaderForLocale: (localeCode: string) => () => Promise<unknown>
): Record<string, () => Promise<unknown>>

makeLoadLocale(
  i18n: I18nLike & Pick<I18nWithResources, 'addResourceBundle'>,
  localeLoaders: Record<string, () => Promise<unknown>>,
  sourceLocale?: string
): (lang: string) => Promise<void>

O bootstrap típico mostra como essas fábricas se compõem. Use setupKeyAsDefaultT como o ponto de entrada usual do aplicativo (key-trim + plural wrapT + translate-ui {sourceLocale}.json opcional). Chamar apenas wrapI18nWithKeyTrim é obsoleto para a integração do aplicativo.

sourcePluralFlatBundle requer uma instância i18next com addResourceBundle(). O campo lng deve corresponder a SOURCE_LOCALE no seu arquivo de inicialização e a sourceLocale em ai-i18n-tools.config.json.

Crie localeLoaders com makeLocaleLoadersFromManifest(uiLanguages, sourceLocale, …) para que as chaves permaneçam alinhadas com targetLocales após generate-ui-languages. Consulte Wire i18next, nextjs-app, console-app e astro-website (makeT personalizado sem i18next).

Auxiliares de exibição

type TranslateFn = (key: string) => string

getUILanguageLabel(lang: UiLanguageManifestRow & { englishName: string }, t: TranslateFn): string
getUILanguageLabelNative(lang: UiLanguageManifestRow & { englishName: string; label: string }): string

UiLanguageManifestRow é exportado como { readonly code: string } — o formato mínimo para linhas de manifesto em makeLocaleLoadersFromManifest. Os auxiliares de exibição também precisam de englishName (e label para getUILanguageLabelNative) das entradas ui-languages.json do seu projeto ({ code, label, englishName, direction }). Consulte Language switcher & RTL para um exemplo completo.

Auxiliares de string

interpolateTemplate(str: string, vars: Record<string, string | number | boolean>): string
flipUiArrowsForRtl(text: string | null | undefined, isRtl: boolean): string | null | undefined

interpolateTemplate substitui placeholders {{name}} onde name corresponde a \w+ (apenas caracteres de palavra ASCII). Chaves com espaços ou hífens não são suportadas. wrapI18nWithKeyTrim usa isso internamente para fallback de localidade de origem quando nenhuma tradução existe.

Em componentes React/i18next, prefira t('key {{var}}', { var }) — o i18next lida com a interpolação nativamente.

Tipos exportados

Também exportado para consumidores TypeScript: I18nLike, I18nWithResources, SetupKeyAsDefaultTOptions, WrapTOptions, UiLanguageManifestRow, TranslateFn.