Cards Translation

Overview

Adaptive Cards are JSON assets, so Greentic translates them by replacing user-facing strings with i18n references and shipping locale catalogs next to the cards.

Current demos use this shape:

{
  "type": "TextBlock",
  "text": "{{i18n:card.main_menu.body_0.text}}"
}

{
  "card.main_menu.body_0.text": "Welcome"
}

Recommended Workflow

Create cards

{
  "type": "AdaptiveCard",
  "version": "1.5",
  "body": [
    {
      "type": "TextBlock",
      "text": "{{i18n:card.welcome.body_0.text}}",
      "size": "Large"
    },
    {
      "type": "TextBlock",
      "text": "{{i18n:card.welcome.body_1.text}}"
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "{{i18n:card.welcome.actions_0.title}}",
      "data": { "action": "start" }
    }
  ]
}

Create the English source catalog

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

Translate the source catalog
Terminal window
```
greentic-i18n-translator translate \
  --langs fr,de,ja \
  --en assets/i18n/en.json
```
This writes or updates locale files next to the English source map.

Validate translated files

greentic-i18n-translator validate \
  --langs fr,de,ja \
  --en assets/i18n/en.json

Package the assets

Keep cards and locale JSON files under the pack or bundle asset tree:

assets/
├── cards/
│   └── welcome.json
└── i18n/
    ├── en.json
    ├── fr.json
    ├── de.json
    └── ja.json

Extraction

The current installed greentic-cards2pack CLI exposes generate; it does not currently expose extract-i18n or --auto-translate. If you need automated extraction, use a project helper script or a custom extraction workflow that:

scans Adaptive Card JSON files
extracts fields such as text, title, label, placeholder, errorMessage, altText, and fallbackText
skips empty strings and pure template expressions
rewrites the card fields to {{i18n:key}}
writes assets/i18n/en.json

The Greentic demo repository includes tools/i18n_extract_cards.py, which follows this pattern for demo packs.

Key Format

Common extracted keys follow this pattern:

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

Part	Source	Example
`prefix`	Usually `card` or app-specific prefix	`card`
`cardId`	Card id or filename	`welcome`
`json_path`	Position in card structure	`body_0`, `actions_1`
`field`	Field name	`text`, `title`, `label`

Examples:

card.welcome.body_0.text
card.welcome.actions_0.title
card.form.body_1.placeholder
card.form.body_0_choices_2.title

What to Translate

Field	Source element
`text`	TextBlock and rich text content
`title`	Actions, toggles, fact titles, and choice titles
`label`	Input labels
`placeholder`	Input placeholders
`errorMessage`	Validation messages
`altText`	Image alt text
`fallbackText`	Fallback content
Fact `value`	FactSet values when the value is user-facing static text

Skip:

empty strings
action data
ids and route names
URLs
pure template expressions such as {{user_name}}
strings that already reference i18n, such as {{i18n:card.welcome.body_0.text}}

Placeholders

Preserve placeholders exactly across translations:

{
  "card.welcome.body_0.text": "Hello, {{name}}!"
}

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

Do not translate placeholder names:

{
  "card.welcome.body_0.text": "Bonjour, {{nom}} !"
}

Troubleshooting

Translator not found

Install or make the translator available on PATH:

cargo install greentic-i18n-translator

Missing translations at runtime

Check that:

the target locale file exists in assets/i18n/
the key exists in that file
the card uses the same key
the active session, team, tenant, or bundle locale is set as expected

Translation validation fails

Run:

greentic-i18n-translator validate \
  --langs fr,de,ja \
  --en assets/i18n/en.json

Then fix missing keys or placeholder mismatches before publishing.