shipi18n

Shipi18n

翻訳の不具合をリリース前に検出します。 Shipi18n はロケールファイルを検査するオープンソースツールです。人間、TMS、AI エージェントによる翻訳でプレースホルダー、複数形、キーが削除されたり壊れたりすると CI を失敗させ、具体的な修正方法を示します。

• 検出対象： 削除または名前が変更されたプレースホルダー（{name}, {{count}}, %{name}, %s, %1$s, %@）、区切り文字が失われた複数形や、言語で必要な形式（ポーランド語の few/many、アラビア語の two）が欠けている複数形（ICU、i18next のキー、Rails、Android、.xcstrings）、無効な ICU MessageFormat、欠落キーや孤立キー、1 つの JSON オブジェクト内に重複して記述されたキー、空文字列や未翻訳の文字列。
• 対応形式： JSON（i18next、vue-i18n、next-intl、フラット形式またはネスト形式）、Rails を含む YAML、Flutter ARB、Apple の .xcstrings、Android の strings.xml、gettext の .po、XLIFF。
• データはアップロードされますか？ いいえ。検査はお使いのマシンまたは CI ランナー上でオフラインで実行されます。
• キーやアカウントは必要ですか？ いいえ。オプションの --semantic レビューと translate で使用するのは、ご自身の LLM キーのみです。

npx @shipi18n/cli check ./locales -s en

終了コード 0 は問題なし、1 は検出事項あり（各項目に 1 行の fix を表示）、2 は使用方法のエラーです。テキスト、JSON、SARIF（GitHub PR アノテーション）、JUnit 形式で出力できます。

モックアップではなく実際の実行結果です。再現するには docs/check-demo.tape を実行してください。

タスクを選ぶ

やりたいこと	使用するもの
ローカルまたは任意の CI でロケールファイルをチェックする	npx @shipi18n/cli check ./locales -s en
GitHub プルリクエストにアノテーションを付ける	Shipi18n/shipi18n-github-action@v3 (セットアップ)
Node を使わずに実行する	Docker ghcr.io/shipi18n/cli または pre-commit フック
npm を使わずに実行する	GitHub リリースから入手できる単一ファイル shipi18n.mjs（SHA-256 とビルド来歴の証明書付き）
Python、Ruby、Go、Java のプロジェクトから使う	同じ CLI を Docker、pre-commit、または単一ファイル経由で使います。インポート可能な Python または Ruby パッケージはありません
AI コーディングエージェントに独自の翻訳をチェックさせる	npx @shipi18n/cli init --agents または MCP サーバー @shipi18n/mcp
構造だけでなく意味もチェックする	ご自身の Anthropic または OpenAI のキーを使って check --semantic を実行
翻訳する（オプション）	ご自身のキーを使って shipi18n translate を実行

できないこと

• ホステッドサービスや TMS ではありません。アカウント、ダッシュボード、料金プランはありません。（以前提供していたホステッド翻訳 API は提供を終了しました。）
• Python や Ruby からインポートするライブラリではありません。任意の CI から実行する CLI です。
• --semantic を指定しない場合は、構造を検査しますが、翻訳が自然に読めるかどうかは検査しません。

実際のプロジェクトで見つかった問題。 実際のプロジェクトで同じコマンドを実行しました。実行時点の Hoppscotch のアフリカーンス語ロケールです（構造ルールのみ。プレースホルダーの検出結果が目立つよう、欠落キーのノイズは無効にしています）。

$ npx @shipi18n/cli check packages/hoppscotch-common/locales -s en \
    --severity 'missing-key=off,untranslated=off,orphan-key=off'

✗ af  coverage 100.0%  7 error(s), 5 warning(s)
    error  import.file_size_limit_exceeded_warning_multiple_files  placeholder-missing — dropped {sizeLimit}
    error  import.file_size_limit_exceeded_warning_single_file  placeholder-missing — dropped {sizeLimit}
    error  state.connected_to  placeholder-missing — dropped {name}
    warning  state.connected_to  placeholder-added — unexpected {naam}
    error  team.invited_to_team  placeholder-missing — dropped {workspace}
    warning  team.invited_to_team  placeholder-added — unexpected {team}
    …

{naam} は {name} を翻訳したものです。vue-i18n がこれを置換することはありません。公開リポジトリをスキャンし、検出したすべての問題を原文と手作業で照合してから、修正を上流に送っています。リポジトリごとの累計はこちらです。 shipi18n.com/oss — 95 個のリポジトリをスキャン · 23 個のリポジトリで壊れた文字列を検証済み · 402 個の文字列を手作業で検証 · 8 個のリポジトリで上流に修正を反映。

リポジトリ	対応内容
Solidus	pt-BR で %{…} 補間が 13 個欠落 — 同日に PR がマージ、コアメンバー 3 人が承認
Plane	チェコ語のトースト通知から {templateName}／{templateType} が欠落 — 3 時間で PR がマージ
nocodb	こちらの issue → メンテナーが 39 個すべてのロケールを対象とする PR を作成。その後、| が機械翻訳によって <unk> に変わっていた 13 個のロケールの複数形 182 件 も、同日に修正
Excalidraw	こちらの issue → 貢献者による修正と、プレースホルダーの一致を検証するテストスイート
Hoppscotch	上記の af の実行結果 — PR がマージ、文字列 7 件
24pullrequests	欠落していた補間 20 件を 2 つの PR で修正。その後、独自のテストスイートに補間チェックを追加
devise_invitable	%{email) の誤記を修正。その後、チェックを CI に追加

スキャンによって自作チェッカーの誤検出が判明するたびに、まず evals/placeholders/corpus.jsonl にテストデータとして追加しました。

チェックによってプロジェクトで問題が見つかった場合は、リポジトリにスターを付けることをご検討ください。スターがあれば、壊れた es.json を抱えた次の人がこのツールを見つけやすくなります。

次に、意味をチェックしたくなったら、ご自身のキーをご用意ください。判定には CLI に加えてプロバイダーの SDK が必要です。

npm i -D @shipi18n/cli @anthropic-ai/sdk       # or `openai`
export ANTHROPIC_API_KEY=sk-ant-...            # or OPENAI_API_KEY
npx @shipi18n/cli check ./locales -s en --semantic

LLM が各ペアを読み、誤訳、欠落、追加を報告します。

⚠ es  coverage 100.0%  0 error(s), 1 warning(s)
    warning  delete  semantic-mistranslation — Translation says 'will save' (guardará)
                     instead of 'will delete' (eliminará/borrará)

すべてのプレースホルダーがそのままで、すべてのキーが存在するため、このファイルは構造チェックに合格します。バグを見つけるには、実際に読まなければなりません。デフォルトでは助言のみを行い、警告は出しますがビルドを失敗させません。

主張ではなく、計測結果です。 判定ツールの作成前にコミットした 228 ペアのコーパス（60d699b）を使用し、しきい値を先に固定した結果、**仕込んだエラー 54 件中 54 件を検出（100%）**し、**問題のないペアでの誤検出は 168 件中 12 件（7.1%）**でした。用語集違反も 6 件中 6 件を検出しました。claude-haiku-4-5、3 パス、約 59k トークンを使用し、156 秒で実行した、独立した 2 回の実行（2026-08-16、2026-08-17）で再現しました。ラベルの正解率は実行ごとに変動しました（100% → 98.1%）。これはモデルによる結果なので、一定値ではなく幅として捉えてください。 ハーネスは evals/semantic/ にあります。ご自身のモデルで実行してください。

サーバーが存在しないため、当社のサーバーを経由するものはありません。ネットワーク通信は、お使いのマシンから選択したプロバイダーへのものだけです。

パッケージ

パッケージ	説明
@shipi18n/core	エンジンです。翻訳チェック、セマンティック判定、プレースホルダー検証に加え、プロバイダーに依存しない構造保持型の翻訳とインクリメンタルモードを提供します。
@shipi18n/cli	CI 向けの shipi18n check ./locales、意味を確認する --semantic、手動編集を保護する lock、必要に応じて使える translate を提供します。
@shipi18n/mcp	MCP サーバーです。Claude Desktop、Cursor、または任意の MCP クライアントからロケールファイルをチェック、差分確認、レビューできます。検証に API キーは不要 です。
vite-plugin-shipi18n	独自の LLM キーを使って、キャッシュ付きでビルド時にロケールファイルを翻訳する Vite プラグインです。
shipi18n-github-action	すべての PR でロケールファイルをチェックします（キー不要、SARIF アノテーション対応）。オプションで BYO キーによる再翻訳もできます。

理由

翻訳の生成は、すでに解決された問題です。ロケールファイルを埋めてくれる優れたツールはいくつもあり、エージェントなら無料で実行できます。結果をチェックするものはありません。 CI は JavaScript を lint し、型を型チェックし、テストを実行します。それなのに、誰も目を通しておらず、誰も監査していないモデルが生成した de.json をそのままリリースしてしまいます。

既存のチェックは構造面に限られています。キーセットを比較して終わりです。これで不足しているキーは見つかります。しかし、すべてのキーとプレースホルダーがそろっていても、ドイツ語ユーザーに意図と正反対のことを伝えてしまう翻訳は見つけられません。

Shipi18n は、2 つの層でその不足しているゲートを提供します。

• 決定論的、オフライン、キー不要。 不足キーと孤立キー、欠落または形式不正のプレースホルダー（{{name}}、{count}、%s、%d、%1$s、$t(...)、%{name}、HTML）、複数形の形式の欠落、空の値、未翻訳の文言、言語ごとのカバレッジを検出します。
• 独自のキーを使うセマンティックチェック。 変更されたキーだけを対象に、LLM を判定者とするチェックを実行します。単一パスの判定スコアは不安定なため、複数パスの多数決を行います。誤訳、省略、追加を報告します。デフォルトではアドバイザリーです。ビルドを失敗させる QA ツールはアンインストールされてしまうからです。

さらに、日々の作業で使いやすくする機能も備えています。

• JSON 以外の形式にも対応。 YAML（.yaml／.yml）、Flutter の .arb、Apple の .xcstrings、Android の strings.xml、gettext の .po／.pot、XLIFF 1.2／2.0 に対応し、%@／%lld 指定子も扱えます。
• CI にネイティブ対応。 正しい終了コード、--fail-on、--min-coverage、PR アノテーション用の SARIF、JUnit に対応します。
• 整理されていないカタログにも導入可能。 --baseline は現在の未対応項目を受け入れ、新たな指摘だけを失敗させます（Stylelint／RuboCop のパターンです）。--severity では、任意のルールの重大度を調整または無効化できます（error|warning|info|off）。
• Node の有無を問わず、どこでも実行可能。 GitHub の Action、pre-commit フック、または Docker イメージ ghcr.io/shipi18n/cli を使って、GitLab／Bitbucket／Jenkins／ローカルで実行できます。Node ツールチェーンは不要です。CLI README を参照してください。
• WordPress の .po ↔ JED 同期。 shipi18n wp-sync は、誰も wp i18n make-json を再実行していないために .po と食い違った JavaScript 翻訳 JSON を検出します。ほかのツールではチェックされない、見つかりにくいバグです。
• プライバシーの事前チェック。 --semantic が LLM にデータを送信する前にスキャンを行い、秘密情報や PII（キー、カード、メールアドレス）を含む文字列を除外します。--detect-secrets を使えば、LLM なしで単独実行できます。
• 手動編集を保護。 shipi18n lock は人が承認した翻訳を記録し、何かがその内容を上書きしたときや、翻訳を残したまま原文が変更されたときに警告します。
• エディターからキーなしで利用可能。 MCP サーバーのバリデーターはモデルを一切呼び出しません。
• 翻訳もできます。 プロバイダーに依存せず、構造を保持し、インクリメンタルに翻訳します。Anthropic と OpenAI に標準対応し、complete(prompt) メソッドを持つ任意のオブジェクトをアダプターとして使用できます。

エディターからチェック — API キー不要

@shipi18n/mcp を使えば、あらゆる MCP クライアントでチェックを実行できます。検証ツールはモデルを呼び出さないため、キーは一切必要ありません。

Claude Code — 1 行で設定できます。

claude mcp add shipi18n -- npx -y @shipi18n/mcp

Claude Desktop / あらゆる MCP クライアント — 設定を貼り付けます。

// claude_desktop_config.json
{
  "mcpServers": {
    "shipi18n": { "command": "npx", "args": ["-y", "@shipi18n/mcp"] }
  }
}

「./locales を英語と照らし合わせてチェックし、スペイン語で問題がある箇所を教えてください。」

review_locales もキー不要で、さらに詳しく確認できます。翻訳のペアとレビュー基準をエージェントに渡し、エージェントが実行中のモデルを使って意味を判断します。

CI でチェック — キー不要

チェックは、TMS、別のツール、エージェント、人間など、あらゆるソースからの翻訳に対応しています。プッシュのたびに実行できます。

npx @shipi18n/cli check ./locales -s en

キーの欠落、プレースホルダーの削除、複数形の集約、空の値、未翻訳の文言を、人が読みやすい形式、JSON、SARIF（GitHub PR の注釈）、または JUnit で報告します。通常の JSON ツリー、YAML、Flutter の .arb、Apple の .xcstrings、Android の strings.xml、gettext の .po／.pot、XLIFF（1.2／2.0）に対応しています。決定論的にオフラインで動作し、LLM も API キーも不要です。

手動で編集した翻訳を保護する

文字列を手動で修正してロックすると、何かが上書きした場合や、その間に英語の原文が変更された場合に、check が警告します。

npx @shipi18n/cli lock ./locales --keys 'legal.*'

.shipi18n/locks.json にはハッシュのみが保存されるため、安心してコミットできます。検出内容は警告として扱われます。人の作業を保護するために、パイプラインを止めることはありません。詳しくはCLI READMEをご覧ください。

翻訳もできます

チェックはどこから取得した翻訳にも使えますが、Shipi18n に翻訳も生成させたい場合は、お使いのキーとモデルを使い、その間に何も介さずに生成できます。

npm i -D @shipi18n/cli @anthropic-ai/sdk       # or `openai`
export ANTHROPIC_API_KEY=sk-ant-...            # or OPENAI_API_KEY
npx @shipi18n/cli translate locales/en.json -t es,fr,de

✔ es → locales/es.json (2 translated, 0 reused)

Node から実行する場合も同様です（SDK の要件は同じです）。

import { translateJSON } from '@shipi18n/core'

const { result, stats } = await translateJSON({
  content: { greeting: 'Hello {{name}}' },
  from: 'en',
  to: 'es',
  provider: 'anthropic',        // 'anthropic' | 'openai' | custom { complete } adapter
})
// result → { greeting: 'Hola {{name}}' }

構造を維持し、プレースホルダーを安全に扱い、増分処理を行います。モデルに送信されるのは、新規または変更されたキーのみです。その後、同じツールで結果をチェックできます。

例

examples/ に実行可能なプロジェクトがあります。react（Vite + react-i18next）、nextjs（App Router）、vue（vue-i18n）、nodejs（@shipi18n/core）を参照してください。いずれかのディレクトリに cd で移動し、インストールして、チェック／翻訳スクリプトを実行します。

開発

pnpm + turbo のモノレポです。

pnpm install
pnpm test          # all packages
pnpm --filter @shipi18n/core test

バージョン管理には Changesets を使用します。追加するには pnpm changeset を実行してください。

コントリビューション

Issue とプルリクエストを歓迎します。CONTRIBUTING.mdをご覧ください。pnpm install && pnpm test を実行すると、モックアダプターを使った 105 件のテストが実行されるため、作業に API キーは必要ありません。

ライセンス

Apache-2.0 © Shipi18n。NOTICEをご覧ください。