i18next から移行する

始める前に

3 つの準備が整えば、インポートできます：

• プロジェクト。 ダッシュボードで作成し、その project_uuid をコピーしてください。
• mcp:* スコープの API キー。 CLI は MCP サーフェス経由で動作するため、プロジェクトに限定されたキーは 403 を返します。生成方法は CLI リファレンスで説明しています。
• Node 18 以降と、<lang>/<namespace>.json として配置された既存の i18next ファイルです（変則的な配置にも対応します）。

1. インストールして初期化する

CLI をグローバルにインストールし、プロジェクトを指す設定を生成し、キーをエクスポートします。

1# one global install — gives you the `sonenta` command (Node >= 18)2npm i -g @sonenta/cli 4# scaffold sonenta.config.json and point it at your project5sonenta init --project <project_uuid> 7# the CLI talks to the MCP surface — use an mcp:* scoped key8export SONENTA_TOKEN=snt_live_<prefix>.<secret>

sonenta init はコミット可能な sonenta.config.json を書き込みます。CI では init をスキップし、--project と環境変数 SONENTA_TOKEN を渡してください。sonenta と SONENTA_* が正式なものです。移行期間中は、旧来の sonenta コマンドと SONENTA_* 変数も引き続き機能します。

2. プレビューしてからインポートする

インポーターは各ファイルのパスを読み取って言語と namespace を推測するため、慣例的な locales/ ツリーであればオプションは不要です。まず dry-run で計画を確認し、その後 --dry-run を外して適用してください。

1# the importer infers (language, namespace) from each path:2#   <lang>/<namespace>.json3locales/4├─ en/5│  ├─ common.json     → language en · namespace common6│  └─ checkout.json   → language en · namespace checkout7└─ fr/8   ├─ common.json     → language fr · namespace common9   └─ checkout.json   → language fr · namespace checkout

1# preview first — no writes, prints exactly what WOULD change2sonenta import "./locales/**/*.json" --dry-run 4# the real run — idempotent, safe to repeat5sonenta import "./locales/**/*.json" 7✓ common · checkout   (en, fr)8  keys           312 created · 0 reused9  translations   624 created · 0 updated · 0 unchanged10  errors 0 · glossary 0 violations 12# non-standard layout? override the inference per file:13sonenta import strings.fr.json --language fr --namespace common

ツリーはネスト形式でもフラット形式でも構いません。どちらも同じようにインポートされます。--status は受信ステータスを設定し（draft または translated、デフォルト translated）、--version はデフォルト以外のバージョンを対象とします。CLDR 辞書（{ one, other }）として表現された複数形は、自動的に複数形として保存されます。

3. CDN に公開する

インポートはプロジェクトを満たし、公開はそれを配信可能にします。リリースを切ると、バンドルが SDK の読み込み元であるグローバル CDN に伝播します。

1# cut a CDN release so the SDK and your build can fetch it2sonenta releases publish 4→ released "main" · propagating to cdn.sonenta.com

リリースはバージョンの不変なスナップショットです。新しいコンテンツをインポートしたら、その都度再公開してください。SDK も静的ビルドも、ともに最新のリリースを取得します。

4. バンドルを検証する

コンテンツがライブであることを確認します。公開されたバンドルは、言語と namespace ごとの素のパブリック JSON ファイルです。1 つを直接取得するか、ダッシュボードでプロジェクトを開いてください。

1# the published bundle is public — no auth needed2curl -s https://cdn.sonenta.com/p/<project_uuid>/main/latest/fr/common.json

ある言語で 404 が出ますか？ まだプロジェクトの言語に含まれていないか、リリースが伝播していません。数秒待ってから再試行してください。

5. SDK を Sonenta に向ける

i18next バックエンドを Sonenta プロバイダーに差し替えてください。t() の呼び出し、キー、namespace はそのままで、翻訳は今公開したばかりの CDN バンドルから届くようになります。

1// src/main.tsx — point @sonenta/react-i18next at the same project2import { SonentaProvider } from "@sonenta/react-i18next"; 4<SonentaProvider5  projectUuid="<project_uuid>"6  token={import.meta.env.VITE_SONENTA_TOKEN}7  defaultLocale="fr"8  namespaces={["common", "checkout"]}9>10  <App />11</SonentaProvider>

ドットを含むキー（バージョン、価格、聖句参照など）がありますか？ keySeparator={false} を設定し、プロジェクトをフラットに切り替えてください。フラットキーとネストキーのガイドを参照してください。それ以外の場合は、ネストのデフォルトでそのまま機能します。

インポーターが扱うこと

• ネスト形式でもフラット形式でも。 どちらの JSON 形式も同じキーにインポートされます。前処理は不要です。
• 複数形。 CLDR の複数形辞書（{ one, other, … }、other は必須）は、自動的に複数形キーになります。
• ファイル単位の耐障害性。 不明な言語や namespace はユニット単位のエラーとして報告され、インポートの残りはそのまま成功します。
• 用語集（glossary）チェック。 インポートされた翻訳はあなたの用語集を通過します。違反はリスト化され、厳格な適用モードではスキップされます。
• 欠落キーのクリーンアップ。 インポートされたキーについて開かれていた欠落キーイベントは、値が届くと同時に解決されます。