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列目以降: 各言語の翻訳テキスト

この並び順に合わないデータは、columns で列を明示的にマッピングできます（後述の列レイアウトのカスタマイズを参照）。

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" \| "xlsx" \| "sheet" | ✅ | データソースの種類 | | path | string | ✅ | ファイルパスまたはGoogle Sheet ID/URL | | credentialType | "none" \| "apiKey" \| "oauth2" \| "jwt" | ✅ | 認証方式 | | localizePath | string | ✅ | 出力先ディレクトリ | | outputType | "dart" \| "typescript" \| "both" | - | 出力形式（デフォルト: dart） | | sheetName | string | - | シート名（既定: 先頭シート） | | skipRows | number | - | 読み飛ばす先頭行数（既定: 0） | | columns | ColumnMapping | - | 列レイアウトの明示指定 |

列レイアウトのカスタマイズ

既定では「1行目がヘッダー、列は key, description, ロケール…の順」を前提とします。 この形に合わないスプレッドシートは columns と skipRows で対応できます。

例えば次のようなシート（ヘッダーが2行あり、A列は無視したい）の場合:

| A（分類） | B（キー） | C（日本語） | D（英語） | E（説明） | | --------- | ---------- | ----------- | --------- | ----------- | | 画面 | key | ja | en | description | | 画面 | helloWorld | こんにちは | Hello | Greeting |

fileType: xlsx
path: ./sheet.xlsx
sheetName: sheet
credentialType: none
localizePath: ./src/i18n/
outputType: typescript
skipRows: 2 # 先頭2行はヘッダーなので読み飛ばす
columns:
  key: B # 列レター、または0始まりの数値インデックス(1)でも可
  description: E
  locales:
    ja: C
    en: D

• columns.key（必須）: キーの列
• columns.description（任意）: 説明の列。省略すると説明は空になります
• columns.locales（必須）: 出力ファイル名（ロケール）と列の対応。定義順が出力順になります
• 列は "B" のような列レターでも、1 のような0始まりの数値インデックスでも指定できます
• columns を指定しない場合は従来どおりの固定レイアウトとして扱われます

設定例

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

• CSV + Dart
• CSV + TypeScript
• xlsx + 列マッピング
• 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.