rokeeru-cli

多言語ロケールリソースの検証・欠落自動補填・CSV相互変換・統計分析 CLI ツール / CLI Tool for Locale Resource Validation, Key Synchronization, CSV Export/Import, and Analytics

日本語 | English

日本語

概要

rokeeru-cli は、多言語ロケールリソース（locales ディレクトリ内の JSON/YAML/TOML ファイル群）の自動走査、翻訳欠落キーの検証・自動補填同期、対話型初期化、CSV形式との相互変換（エクスポート／インポート）、言語間差分比較、および進捗可視化を行うデベロッパー向け CLI ツールです。

CI/CD パイプラインに組み込むことで、未翻訳キーや変数の誤りが残ったままデプロイされるのを自動的にブロックできます。

使用方法

# cli ディレクトリをローカルリンクして rokeeru コマンドとして使用
cd cli && npm link

rokeeru check ./locales --default-locale en
rokeeru stats ./locales

利用可能なサブコマンド

1. rokeeru check [dir]

指定されたディレクトリ内のすべてのロケールファイルを検証し、基準言語と比較します。

• オプション:
  • --default-locale <lang>: 基準言語コード（デフォルト: en）
  • --format <pretty|json>: 出力形式の指定（デフォルト: pretty）
  • --strict: 浮遊キー（基準言語に存在しないキー）検出時も Exit Code 1 とする
  • --no-bun: Bun 自動ハンドオーバーをスキップし、Node.js で強制実行する

2. rokeeru sync [dir] / fix

基準言語のリソースを基準として、他言語で不足しているキーを自動挿入・同期します。

• オプション:
  • --default-locale <lang>: 基準言語コード（デフォルト: en）
  • --placeholder <text>: 補填する文字列（デフォルト: ""）
  • --dry-run: ファイル更新を行わずに結果プレビューのみ表示

3. rokeeru export [dir] [out.csv]

ロケールファイルを翻訳作業用の CSV ファイルへエクスポートします。

• オプション:
  • --default-locale <lang>: 基準言語コード（デフォルト: en）
  • --target-locale <lang>: 出力対象の特定言語（未指定時は全言語）

4. rokeeru import [in.csv] [dir]

翻訳作業完了後の CSV ファイルを読み込み、元のロケールファイルへ反映・書き戻します。

• オプション:
  • --dry-run: 書き戻しを行わずに確認のみ実施

5. rokeeru diff [dir]

基準言語と対象言語のキー不足・空文字・浮遊キーの差分を比較表示します。

• オプション:
  • --base-locale <lang>: 比較元言語（デフォルト: ja）
  • --target-locale <lang>: 比較先言語（デフォルト: en）

6. rokeeru stats [dir]

各言語の総キー数、ユニークキー数、および翻訳達成率 (%) とプログレスバーをレポート表示します。

• オプション:
  • --format <pretty|json>: 出力形式の指定（デフォルト: pretty）

7. rokeeru init

対話形式で rokeeru.config.json および推奨ディレクトリ構造を自動生成します。（-y オプションで非対話形式の静的出力も可能）

Bun ランタイム自動ハンドオーバー

システム環境に bun ランタイムがインストールされている場合、node 経由で呼び出された場合でも自動的に bun プロセスへ切り替えて高速実行を行います。 Node.js 環境で強制実行したい場合は、--no-bun オプションまたは環境変数 ROKEERU_NO_BUN=1 を指定してください。

CI/CD パイプラインへの組み込み

GitHub Actions 等のワークフローに組み込むことで、検証失敗時に非ゼロ（Exit Code 1）を返してビルドを即座にブロックします。

- name: Validate Locales
  run: rokeeru check ./locales --default-locale en --strict

LICENSE

このプロジェクトのライセンスは MIT ライセンスです。詳しくはLICENSE.MITをお読みください。また、サードパーティライセンスはNOTICE.mdに表記してあります。

English

Overview

rokeeru-cli is a developer CLI tool designed to automatically scan multi-language locale resources (JSON/YAML/TOML files), validate missing keys, synchronize placeholders, export/import translations via CSV format, diff locales, and report completion statistics.

By integrating rokeeru-cli into your CI/CD pipeline, you can automatically block deployments that contain missing translation keys or variable mismatches.

Usage

# Link cli module locally to use rokeeru command
cd cli && npm link

rokeeru check ./locales --default-locale en
rokeeru stats ./locales

Subcommands

1. rokeeru check [dir]

Scans and validates all locale files in the specified directory against the baseline language.

• Options:
  • --default-locale <lang>: Baseline language code (Default: en)
  • --format <pretty|json>: Output format (Default: pretty)
  • --strict: Treats extra/floating keys absent in baseline as errors (Exit Code 1)
  • --no-bun: Skips Bun automatic handover and forces execution on Node.js

2. rokeeru sync [dir] / fix

Synchronizes missing keys from baseline into target locale files with placeholder values.

• Options:
  • --default-locale <lang>: Baseline language code (Default: en)
  • --placeholder <text>: Placeholder string to insert (Default: "")
  • --dry-run: Preview changes without updating files

3. rokeeru export [dir] [out.csv]

Exports locale JSON files into a CSV file for translators.

• Options:
  • --default-locale <lang>: Baseline language code (Default: en)
  • --target-locale <lang>: Specific target locale to export

4. rokeeru import [in.csv] [dir]

Imports translated CSV file back into rokeeru locale JSON files.

• Options:
  • --dry-run: Preview changes without modifying files

5. rokeeru diff [dir]

Compares key differences, empty values, and extra keys between base and target locales.

• Options:
  • --base-locale <lang>: Base language code (Default: ja)
  • --target-locale <lang>: Target language code (Default: en)

6. rokeeru stats [dir]

Reports language counts, unique key metrics, completion percentages (%), and progress bars.

• Options:
  • --format <pretty|json>: Output format (Default: pretty)

7. rokeeru init

Interactively generates recommended rokeeru.config.json and directory structure. (Use -y for non-interactive output)

Bun Runtime Automatic Handover

If the bun runtime is detected in your system environment, rokeeru-cli automatically hands over execution to bun for high-performance processing, even when invoked via node. To force Node.js execution, supply the --no-bun option or set ROKEERU_NO_BUN=1.

CI/CD Pipeline Integration

Integrate rokeeru-cli into GitHub Actions to fail the workflow (Exit Code 1) when validation fails.

- name: Validate Locales
  run: rokeeru check ./locales --default-locale en --strict

LICENSE

This project is licensed under the MIT License. See LICENSE.MIT for details. Third-party licenses are documented in NOTICE.md.