i18n Overview

Introduction

Greentic provides comprehensive internationalization (i18n) support through the greentic-i18n library. It enables:

• Deterministic string identifiers
• Locale-based message retrieval
• Adaptive Card translation
• Runtime language switching

Key Features

Deterministic IDs

I18nId v1 spec uses BLAKE3 hashing for consistent, collision-resistant identifiers.

Multi-Format

Support for JSON, YAML, PO, and XLIFF translation formats.

Cards Integration

Built-in support for translating Adaptive Cards.

Runtime Switching

Change languages per-session without restart.

How It Works

Source String: "Hello, World!"
       │
       ▼
┌─────────────────────────────────┐
│     BLAKE3 Hash Function        │
│  blake3(normalize(string))      │
└─────────────────────────────────┘
       │
       ▼
I18nId: "i18n:v1:abc123def456"
       │
       ▼
┌─────────────────────────────────┐
│      Translation Lookup         │
│   locale_map[id] → "Halo!"     │
└─────────────────────────────────┘

Quick Start

1. Extract Strings

For Adaptive Cards:

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

2. Translate

Using greentic-i18n-translator (powered by Codex CLI):

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

Or auto-translate during pack generation:

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

3. Load in Runtime

i18n:
  default_locale: "en"
  locales:
    en: "translations/en.json"
    id: "translations/id.json"
    ja: "translations/ja.json"

4. Use in Flows

- id: greet
  type: reply
  config:
    message_key: "i18n:v1:abc123"  # Resolved based on session locale

Locale Resolution

The locale is resolved in this order:

1. Session-level locale (set per user)
2. Team-level default
3. Tenant-level default
4. Global default

# Set session locale
- id: set_language
  type: state
  config:
    action: set
    key: "locale"
    value: "id"  # Indonesian

Supported Languages

Any language is supported. Common configurations:

Locale	Language
en	English
id	Indonesian
ja	Japanese
zh	Chinese
es	Spanish
de	German

Next Steps

• I18nId Specification
• Cards Translation