コンテンツへスキップ
Sonenta

ガイド · 移行

i18next から移行する

すでに i18next で本番運用していますか? @sonenta/react-i18nextreact-i18next のドロップイン置き換え(drop-in)です。useTranslation()t() の API は同じで、プロバイダーを差し替えるだけで翻訳が CDN からライブで届きます。既存の locales/ ファイルを 1 つのコマンドで Sonenta に取り込み、あとはコードをそのまま維持できます。インポートは欠落しているキーを作成し、すべての翻訳を upsert し、完全に冪等です。そのため CI から不安なく再実行できます。これがすべての手順です:インストール、インポート、公開、検証、SDK の接続です。

始める前に

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

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

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

terminal
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 を渡してください。sonentaSONENTA_* が正式なものです。移行期間中は、旧来の sonenta コマンドと SONENTA_* 変数も引き続き機能します。

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

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

your repo
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
terminal
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 に伝播します。

terminal
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 つを直接取得するか、ダッシュボードでプロジェクトを開いてください。

terminal
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 バンドルから届くようになります。

main.tsx
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} を設定し、プロジェクトをフラットに切り替えてください。フラットキーとネストキーのガイドを参照してください。それ以外の場合は、ネストのデフォルトでそのまま機能します。

いつでも再実行可能

sonenta import は冪等です。同一のコンテンツを再インポートしても何も変わりません(0 created, 0 updated, N unchanged)。CI に組み込めば、Sonenta をリポジトリと同期した状態に保てます。欠落しているものだけを作成し、実際に変更されたものだけを更新します。

インポーターが扱うこと

次のステップ