Cards の翻訳

概要

Greentic は、Adaptive Cards を複数の言語に翻訳することをサポートしています。方法は次の 2 つです。

1 コマンド: generate --auto-translate（抽出 + 翻訳 + ビルドを実行）
ステップごと: extract → translate → build

クイックスタート（1 コマンド）

greentic-cards2pack generate \
  --cards ./cards \
  --out ./my-pack \
  --name my-pack \
  --auto-translate \
  --langs fr,de,ja

これで完了です。pack には assets/i18n/en.json、fr.json、de.json、ja.json が含まれます。

ステップ別ワークフロー

カードを作成する

{
  "type": "AdaptiveCard",
  "version": "1.4",
  "body": [
    { "type": "TextBlock", "text": "Welcome!", "size": "Large" },
    { "type": "TextBlock", "text": "How can I help you today?" }
  ],
  "actions": [
    { "type": "Action.Submit", "title": "Get Help" },
    { "type": "Action.Submit", "title": "Contact Support" }
  ]
}

翻訳対象の文字列を抽出する

greentic-cards2pack extract-i18n \
  --input ./cards \
  --output i18n/en.json

出力:

{
  "card.welcome.body_0.text": "Welcome!",
  "card.welcome.body_1.text": "How can I help you today?",
  "card.welcome.actions_0.title": "Get Help",
  "card.welcome.actions_1.title": "Contact Support"
}

greentic-i18n-translator で翻訳する
Terminal window
```
greentic-i18n-translator translate \
  --langs fr,ja \
  --en i18n/en.json
```
同じディレクトリに i18n/fr.json と i18n/ja.json が作成されます。

greentic-i18n-translator は翻訳に Codex CLI を使用します。cargo install greentic-i18n-translator でインストールしてください。

pack を生成する

greentic-cards2pack generate \
  --cards ./cards \
  --out ./my-pack \
  --name my-pack

キー形式

抽出されるキーは、次のパターンに従います。

{prefix}.{cardId}.{json_path}.{field}

Part	Source	Example
`prefix`	`--prefix` flag（デフォルト: `card`）	`card`
`cardId`	`greentic.cardId` field または filename	`welcome`
`json_path`	card structure 内の位置	`body_0`, `actions_1`
`field`	field 名	`text`, `title`, `label`

例:

card.welcome.body_0.text → 最初の TextBlock の text
card.welcome.actions_0.title → 最初の action の title
card.form.body_1.placeholder → 2 番目の body 要素の placeholder
card.form.body_0_choices_2.title → 3 番目の choice option の title

用語集

brand 名や technical term は、翻訳全体で一貫性を保ってください。

{
  "Greentic": "Greentic",
  "Dashboard": "Dashboard",
  "CLI": "CLI"
}

どちらの方法でも使用できます。

# One command
greentic-cards2pack generate \
  --cards ./cards --out ./pack --name demo \
  --auto-translate --langs fr,de \
  --glossary glossary.json

# Step by step
greentic-i18n-translator translate \
  --langs fr,de \
  --en i18n/en.json \
  --glossary glossary.json

抽出対象

Field	Source Element
`text`	TextBlock, RichTextBlock
`title`	Actions, toggles, fact titles
`label`	Input labels
`placeholder`	Input placeholders
`errorMessage`	Validation messages
`altText`	Image alt text
`fallbackText`	Fallback content
`value`	Fact values

自動的にスキップされるもの:

空文字列
純粋な Handlebars template: {{variable}}
変数参照: ${var}
既存の i18n pattern: $t(key)（--include-existing を指定しない限り）

Runtime 翻訳

locale を設定する

i18n:
  default_locale: "en"
  locales:
    en: "assets/i18n/en.json"
    fr: "assets/i18n/fr.json"
    ja: "assets/i18n/ja.json"

flow で locale を設定する

- id: set_language
  type: state
  config:
    key: "locale"
    value: "fr"
  next: show_welcome

- id: show_welcome
  type: adaptive-card
  config:
    card: "cards/welcome"
    # Card text automatically resolved based on session locale

エラーハンドリング

翻訳失敗は 致命的ではありません。greentic-i18n-translator がある言語で失敗しても、次のようになります。

pack のビルド自体は成功する
.cards2pack/manifest.json に warning が記録される
英語バンドル（en.json）は常に作成される

warning の確認:

cat my-pack/.cards2pack/manifest.json | jq '.warnings[] | select(.kind == "translation")'

トラブルシューティング

translator が見つからない

auto-translation failed: failed to execute greentic-i18n-translator

インストール: cargo install greentic-i18n-translator

またはカスタムパスを設定: export GREENTIC_I18N_TRANSLATOR_BIN=/path/to/translator

Runtime で翻訳が見つからない

対象言語の bundle にキーが存在しない場合、runtime は英語の元テキストにフォールバックします。

placeholder が翻訳で失われる

Handlebars placeholder が保持されていることを確認してください。

// Correct
{ "card.welcome.body_0.text": "Bonjour, {{name}} !" }

// Wrong — placeholder lost
{ "card.welcome.body_0.text": "Bonjour, nom !" }