Skip to main content

Translations

SitePack themes support multi-language translation files, allowing you to easily localize your theme for different regions and languages.

The Translations Folder​

All translation files should be placed in the translations/ directory at the root of your theme. Each file should be named after the locale code it represents, using the .json extension.

Locale Case Sensitivity​

SitePack stores and looks for locale files in lowercase. Always use lowercase for the filename, even if the locale is typically written with uppercase letters.

  • Correct: nl_be.json, en_us.json
  • Incorrect: nl_BE.json, en_US.json

Supported Locales​

SitePack supports both language-level locales (e.g., en.json, nl.json) and regional locales (e.g., nl_be.json, en_us.json, de_at.json, fr_ca.json).

/
├── translations/
│   ├── en.json
│   ├── nl.json
│   ├── nl_be.json
│   ├── de_at.json
│   └── fr_ca.json
└── ...

Locale Resolution & Fallbacks​

SitePack uses a smart fallback mechanism to ensure that users always see the most relevant translation available. When a regional locale like nl_be (Dutch - Belgium) is used, SitePack follows this resolution order:

  1. Specific Regional Locale: It first looks for the key in translations/nl_be.json.
  2. Base Language Locale: If the key is not found (or the file doesn't exist), it falls back to the base language file translations/nl.json.
  3. Key Name: If the key is still not found in any file, it returns the key name itself (e.g., error.404_title).

Fallback Example​

Imagine you have two translation files:

translations/nl.json

{
  "cart": {
    "title": "Winkelwagen",
    "checkout": "Afrekenen"
  }
}

translations/nl_be.json

{
  "cart": {
    "checkout": "Bestellen"
  }
}

If the current locale is nl_be:

  • {{ 'cart.title' | trans }} will return "Winkelwagen" (falling back to nl.json).
  • {{ 'cart.checkout' | trans }} will return "Bestellen" (found in nl_be.json).

This mechanism allows you to maintain a comprehensive base language file and only override specific terms that differ in a particular region.

Defining Translations​

Translations are defined in JSON format. You can use nested objects to organize your translation keys logically.

For example, to define a 404 error message in Dutch (translations/nl.json):

{
  "error": {
    "404_title": "Pagina niet gevonden"
  }
}

Using Translations in Templates​

To use a translation key in your Twig templates, use the trans filter. This filter takes the translation key as input and returns the translated string for the current locale.

<h1>{{ 'error.404_title' | trans }}</h1>

If the current locale is set to Dutch (nl), the output will be:

<h1>Pagina niet gevonden</h1>

Key Mapping​

The trans filter uses dot notation to access nested keys in your JSON files. For example, 'error.404_title' maps to the 404_title key inside the error object.

Translation Variables​

The trans filter also supports variables for dynamic content. You can include placeholders in your JSON translation files using {{ variable_name }}.

translations/en.json

{
  "welcome": "Welcome back, {{ name }}!"
}

template.twig

<p>{{ 'welcome' | trans({ 'name': 'John' }) }}</p>

Output:

<p>Welcome back, John!</p>