> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Internationalization

> Locale-aware content with the :i18n operator in penscript

penscript supports locale-aware content through the `:i18n` operator. This allows forms, notifications, case labels, and any text content to be served in the right language automatically — based on the contact's or user's locale.

## Inline Translations: `:i18n`

Returns a localized string based on the active locale. The scope must include a `locales` array that defines the user's preferred languages, ordered by preference.

```json theme={null}
{
  ":i18n": {
    "fr": "Bonjour {user.given_name}",
    "en": "Hello {user.given_name}"
  }
}

// Scope (FR): { "locales": ["fr", "en"], "user": { "given_name": "Marie" } }
// Result: "Bonjour Marie"

// Scope (EN): { "locales": ["en", "fr"], "user": { "given_name": "Alex" } }
// Result: "Hello Alex"
```

The operator checks the `locales` array in order and returns the first matching translation. If the preferred locale isn't available, it falls back to the next one in the list.

## Variable Interpolation

Translations support full variable interpolation — any penscript variable can be used inside the translated strings:

```json theme={null}
{
  ":i18n": {
    "fr": "Votre dossier #{case.reference} a été créé le {case.created_at | formatDdMmYyyy}.",
    "nl": "Uw dossier #{case.reference} werd aangemaakt op {case.created_at | formatDdMmYyyy}.",
    "en": "Your case #{case.reference} was created on {case.created_at | formatDdMmYyyy}."
  }
}
```

Variables are resolved after the locale is selected, so each translation can reference any value available in the scope.

## Where to Use `:i18n`

The `:i18n` operator works anywhere penscript is evaluated:

* **Form labels and descriptions** — display element titles in the contact's language
* **Notification content** — emails and SMS in the right language
* **Welcome and completion pages** — localized form instructions
* **Case status labels** — localized status names for display
* **Document generation** — language-specific content in generated documents

For forms, the contact's language preference determines which translation is shown. For internal-facing content, the workspace member's language is used.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Variables & Scope" icon="brackets-curly" href="/penscript/variables">
    Variable interpolation in strings
  </Card>

  <Card title="Logic & Comparisons" icon="code-branch" href="/penscript/logic">
    Conditional content by locale
  </Card>

  <Card title="How penscript Works" icon="gears" href="/penscript/how_it_works">
    :i18n in notifications
  </Card>

  <Card title="Cases" icon="folder" href="/cases/introduction">
    Contact language preferences
  </Card>
</CardGroup>