ランタイムヘルパー

これらのヘルパーは'ai-i18n-tools/runtime'からエクスポートされ、任意のJavaScript環境（ブラウザ、Node.js、Deno、Edge）で動作します。これらはi18nextやreact-i18nextからインポートしません。

これらはアプリのブートストラップ（src/i18n.js）、言語スイッチャー、および方向や文字列ユーティリティを必要とするReact以外のコードで使用してください。エンドツーエンドの設定については、i18nextの設定から始めてください。言語メニューやRTLについては、言語スイッチャーとRTLを参照してください。

インポートパターン

デフォルトエクスポートはi18next-helperの名前空間のみです（defaultI18nInitOptions, setupKeyAsDefaultT, wrapT, makeLoadLocale, …）。interpolateTemplate、flipUiArrowsForRtl、表示ヘルパー、および型は名前付きエクスポートとしてインポートしてください。これらはデフォルトエクスポートのプロパティではありません。

// 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';

クイックリファレンス

エクスポート	役割
defaultI18nInitOptions(sourceLocale?)	キーをデフォルトとして使用する設定のための標準的なi18nextのinit()オプション。
setupKeyAsDefaultT(i18n, options)	推奨されるアプリのエントリポイント — キートリムラッパー、オプションのソース複数形バンドル、複数形対応のwrapT。
wrapT(i18n, options)	下位レベルの複数形t()ラッパー（通常はsetupKeyAsDefaultTによってインストールされます）。
buildPluralIndexFromStringsJson(entries)	"plural": trueを使用してstrings.jsonの行からwrapTが使用するliteral → groupIdマップを構築します。
extractInterpolationNamesForWrap(message)	ソース文字列から {{var}} プレースホルダー名を解析します。
wrapI18nWithKeyTrim(i18n)	キートリム + ソースロケール {{var}} フォールバックのみ。アプリ配線では 非推奨 — setupKeyAsDefaultT を使用してください。
makeLocaleLoadersFromManifest(manifest, sourceLocale, makeLoader)	ui-languages.jsonからmakeLoadLocale用のlocaleLoadersマップを構築します（sourceLocaleを除くすべてのcode）。
makeLoadLocale(i18n, loaders, sourceLocale?)	addResourceBundleを介した非同期ロケールJSON読み込み用のファクトリ。
RTL_LANGS	RTLベース言語コードの読み取り専用セット（バンドルされたカタログにロケールが存在しない場合のフォールバック）。
getTextDirection(lng)	BCP-47コードに対応する'ltr'または'rtl'を返す。
applyDirection(lng, element?)	document.documentElement（ブラウザ）またはカスタム要素にdir属性を設定します。
getUILanguageLabel(lang, t)	翻訳時にt(englishName)を使用する言語メニューラベル。
getUILanguageLabelNative(lang)	マニフェストフィールドのみからの言語メニューラベル（englishName / label）。
interpolateTemplate(str, vars)	プレーンテキストに対するローレベルの {{var}} 置換（React/i18next では t() を推奨）。
flipUiArrowsForRtl(text, isRtl)	RTLレイアウト向けに→を←に反転。

RTL ヘルパー

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

getTextDirectionはバンドルされたdata/ui-languages-complete.jsonカタログを最初に参照し（generate-ui-languagesと同じソース）、カタログにないコードについてはRTL_LANGSにフォールバックします。

applyDirectionはNode.jsで安全に使用できます — documentが利用できない場合は何もしません。ブラウザでは、document.documentElementを更新するためにelementを省略します。言語変更時にこれを設定します：i18n.on('languageChanged', applyDirection)。

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>

通常のアプリケーションエントリポイントとして setupKeyAsDefaultT を使用してください（キーのトリミング＋複数形 wrapT＋オプションの translate-ui {sourceLocale}.json）。アプリケーションの配線において、単独で wrapI18nWithKeyTrim を呼び出すことは非推奨です。

sourcePluralFlatBundleには、addResourceBundle()を持つi18nextインスタンスが必要です。lngフィールドは、ブートストラップファイル内のSOURCE_LOCALEおよびai-i18n-tools.config.json内のsourceLocaleと一致する必要があります。

makeLocaleLoadersFromManifest(uiLanguages, sourceLocale, …)を使用してlocaleLoadersをビルドし、generate-ui-languagesの後もキーがtargetLocalesと整合性を保つようにします。Wire i18next、nextjs-app、console-app、およびastro-website（i18nextを使用しないカスタムmakeT）を参照してください。

表示ヘルパー

type TranslateFn = (key: string) => string

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

UiLanguageManifestRowは{ readonly code: string }としてエクスポートされます。これはmakeLocaleLoadersFromManifestのマニフェスト行の最小構成です。表示ヘルパーは、プロジェクトのui-languages.jsonエントリ（{ code, label, englishName, direction }）からenglishName（およびgetUILanguageLabelNative用のlabel）も必要とします。完全な例については、Language switcher & RTLを参照してください。

文字列ヘルパー

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

interpolateTemplate は name が \w+（ASCII 単語文字のみ）に一致する {{name}} プレースホルダーを置換します。スペースやハイフンを含むキーはサポートされていません。wrapI18nWithKeyTrim は翻訳が存在しない場合のソースロケールフォールバックとして内部的にこれを使用しています。

React/i18next コンポーネントでは、t('key {{var}}', { var }) を使用してください — i18next は補間をネイティブに処理します。

エクスポートされる型

TypeScriptコンシューマー向けにエクスポートされるもの: I18nLike、I18nWithResources、SetupKeyAsDefaultTOptions、WrapTOptions、UiLanguageManifestRow、TranslateFn。