l10n-generator

Google SheetsまたはCSVファイルから、Dart ARBファイルとTypeScriptのローカライゼーションファイルを自動生成するCLIツール

📚 ドキュメント

詳細なドキュメントはdocsディレクトリを参照してください:

• 🚀 クイックスタート - 5分で始める
• 💻 CLI使用方法 - 完全ガイド
• 🧪 テスト環境 - 環境構築
• 🔐 OAuth2認証 - プライベートシート対応

✨ 特徴

• 📝 複数のデータソース対応: CSV、Google Sheets（API Key、OAuth2、JWT認証）
• 🎯 複数の出力形式: Dart ARB、TypeScript型定義 + 各言語ファイル
• 🔧 YAML設定ファイル: シンプルで読みやすい設定
• 🚀 npxで即実行: インストール不要で実行可能
• 🌍 多言語サポート: 任意の数の言語に対応

📦 インストール

グローバルインストール

npm install -g l10n-generator

プロジェクトにインストール

npm install --save-dev l10n-generator
# or
pnpm add -D l10n-generator

npxで直接実行（インストール不要）

npx l10n-generator --config your-config.yaml

🚀 クイックスタート

1. 設定ファイルを作成

プロジェクトルートにl10n-generator.config.yamlを作成します。

fileType: csv
path: ./localization.csv
credentialType: none
localizePath: ./src/i18n/
outputType: both # dart | typescript | both

2. ローカライゼーションデータを準備

CSVファイルの形式:

key,description,ja,en
hello,Greeting,こんにちは,Hello
goodbye,Farewell,さようなら,Goodbye
welcome,Welcome message,ようこそ、{name}さん,"Welcome, {name}"

• 1列目: キー（変数名）
• 2列目: 説明
• 3列目以降: 各言語の翻訳テキスト

3. 実行

# デフォルト設定ファイルを使用
l10n-generator

# カスタム設定ファイルを指定
l10n-generator --config custom.config.yaml

# npxで実行
npx l10n-generator --config your-config.yaml

📤 出力形式

Dart ARB形式 (outputType: dart)

output/
├── app_ja.arb
└── app_en.arb

app_ja.arbの内容例:

{
  "@@locale": "ja",
  "hello": "こんにちは",
  "@hello": {
    "description": "Greeting"
  },
  "welcome": "ようこそ、{name}さん",
  "@welcome": {
    "description": "Welcome message",
    "placeholders": {
      "name": {
        "type": "String",
        "example": "name"
      }
    }
  }
}

TypeScript形式 (outputType: typescript)

output/
├── translation.ts         # 型定義
├── translateFunction.ts   # ヘルパー関数
├── ja.ts                  # 日本語翻訳
└── en.ts                  # 英語翻訳

translation.tsの内容例:

export interface Translation {
  /**
   * こんにちは: Greeting
   */
  "hello": string;
  /**
   * ようこそ、{name}さん: Welcome message
   */
  "welcome": string;
  /**
   * {count}件: Count label
   */
  "common.count": string;
}

ja.tsの内容例:

import { Translation } from "./translation";

export const translation: Translation = {
  hello: "こんにちは",
  welcome: "ようこそ、{name}さん",
  "common.count": "{count}件",
};

⚙️ 設定ファイルの詳細

基本設定

| フィールド | 型 | 必須 | 説明 | | ---------------- | ----------------------------------------- | ---- | ------------------------------------- | | fileType | "csv" \| "sheet" | ✅ | データソースの種類 | | path | string | ✅ | ファイルパスまたはGoogle Sheet ID/URL | | credentialType | "none" \| "apiKey" \| "oauth2" \| "jwt" | ✅ | 認証方式 | | localizePath | string | ✅ | 出力先ディレクトリ | | outputType | "dart" \| "typescript" \| "both" | - | 出力形式（デフォルト: dart） |

設定例

詳細な設定例はexamplesディレクトリを参照してください。

• CSV + Dart
• CSV + TypeScript
• Google Sheets + API Key
• Google Sheets + OAuth2
• Google Sheets + JWT

🔧 Google Sheets の設定

API Keyを使用する場合

1. Google Cloud Consoleでプロジェクトを作成
2. Google Sheets APIを有効化
3. APIキーを作成
4. スプレッドシートを「リンクを知っている全員」に共有設定

OAuth2を使用する場合

1. Google Cloud ConsoleでOAuth 2.0クライアントIDを作成

2. トークン取得ヘルパーを実行してトークンを取得

   node lib/helpers/oauth2-helper.js

3. 取得したトークンを設定ファイルに追加

詳しくはOAUTH2-SETUP.mdを参照してください。

Service Account（JWT）を使用する場合

1. Google Cloud Consoleでサービスアカウントを作成
2. JSONキーファイルをダウンロード
3. スプレッドシートをサービスアカウントのメールアドレスと共有
4. JSONの内容を設定ファイルのjwtフィールドに記載

💻 CLIオプション

l10n-generator [オプション]

コマンド:
  l10n-generator diagnose  Google Sheets API接続の診断

オプション:
  --config     設定ファイルのパス (デフォルト: l10n-generator.config.yaml)
  --diagnose   接続診断を実行
  -h, --help   ヘルプを表示
  --version    バージョンを表示

例:
  l10n-generator                          デフォルト設定ファイルで生成
  l10n-generator --config custom.yaml     カスタム設定で生成
  l10n-generator diagnose                 test.config.yamlで診断実行
  l10n-generator diagnose --config custom.yaml  カスタム設定で診断

診断コマンド

Google Sheets APIの接続に問題がある場合、診断コマンドで原因を特定できます:

l10n-generator diagnose --config test.config.yaml

診断コマンドは以下をチェックします:

• 設定ファイルの形式
• APIキーの有効性
• Google Sheets APIの有効化状態
• スプレッドシートの共有設定
• データ形式の妥当性

📝 スクリプトに組み込む

package.jsonにスクリプトを追加:

{
  "scripts": {
    "i18n": "l10n-generator",
    "i18n:watch": "nodemon --watch localization.csv --exec l10n-generator"
  }
}

実行:

npm run i18n

🐛 トラブルシューティング

出力ディレクトリが見つからない

出力先ディレクトリは自動作成されません。事前に作成してください:

mkdir -p src/i18n

Google Sheets APIエラー

• API Keyが正しいか確認
• Google Sheets APIが有効化されているか確認
• スプレッドシートの共有設定を確認

詳しいテスト環境のセットアップ手順はTESTING.mdを参照してください。

🤝 Contributing

Contributions, issues and feature requests are welcome! Feel free to check issues page.

📝 License

Copyright © 2022-2026 Tomohiro Ueki. This project is MIT licensed.