i18n Overview

Introduction

Greentic i18n is based on locale-specific JSON catalogs that travel with CLIs, components, application packs, extension packs, or bundle assets. Runtime code resolves a key for the active locale and falls back to broader locales or English/source text when needed.

Use i18n for:

Adaptive Card text, titles, labels, placeholders, and validation messages
WebChat labels and tenant-specific UI text
component QA/setup questions
CLI and wizard messages
templates, prompts, and app-specific messages that should vary by locale

Key Features

JSON Catalogs

Locale files are JSON key/value maps such as assets/i18n/en.json, de.json, and ja.json.

Pack Assets

Application packs and bundle assets can carry translated strings next to the cards and flows that use them.

Cards Integration

Adaptive Cards can reference keys with {{i18n:key}} placeholders.

Locale Fallback

Locale lookup falls back from exact locale to base language, then English/source text.

Catalog Format

Current Greentic packs and demos use flat JSON maps:

{
  "card.main_menu.body_0.text": "Welcome",
  "card.main_menu.actions_0.title": "Start",
  "qa.install.title": "Configure the component"
}

Locale files use the same keys:

{
  "card.main_menu.body_0.text": "Willkommen",
  "card.main_menu.actions_0.title": "Starten",
  "qa.install.title": "Komponente konfigurieren"
}

When a catalog is embedded in CLI tooling, the local i18n runtime normalizes locale tags and checks this chain:

requested locale -> base language -> en -> key/source fallback

For example, en-US can use en, and ja-JP can use ja when only the base language catalog exists.

Adaptive Card References

Cards can keep text fields as i18n references:

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

The Adaptive Card component or messaging surface can resolve those references using the active locale and available catalog files.

Translation Workflow

Put source strings in assets/i18n/en.json.
Reference those keys from cards, templates, QA, or UI assets.
Generate or maintain translated JSON files with the same keys.
Ship the locale files with the pack or as bundle-level asset overrides.
Test at least one non-English locale before publishing.

Use greentic-i18n-translator when you already have an English source map:

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

Validate translated files before publishing:

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

Locale Lists

Many demos include assets/i18n/locales.json to record bundled locales:

[
  "en",
  "de",
  "es",
  "fr",
  "ja",
  "zh"
]

The exact supported locales are deployment and pack dependent. Do not promise a language unless the pack or bundle actually ships that locale file.