# Translations

Translation settings enable multi-language support for editor labels and default values in your sections. All labels, placeholders, descriptions, and default text values used in [Content Editors](/site-themes/develop-site-themes/sections/settings/content-editors.md) and [Design Editors](/site-themes/develop-site-themes/sections/settings/design-editors.md) are resolved from translation keys defined here. These strings are visible to merchants in the Instant Site Editor and can be customized by them.

### Overview <a href="#overview" id="overview"></a>

Translations are defined in a single `translations.ts` file inside the `settings/` directory:

```
sections/<section-name>/settings/
└── translations.ts
```

The file exports a `TranslationSettings` object — a record keyed by language code, where each language maps translation keys to their localized strings.

### Type Definition <a href="#type-definition" id="type-definition"></a>

```vue
TranslationSettings = Record<LanguageCode, Record<LabelKey, string>>
```

Where:

* **`LanguageCode`** — A valid language code matching the pattern: `xx` or `xx_XX` (e.g., `en`, `fr`, `nl`, `en_US`, `zh_Hans`, `pt_BR`)
* **`LabelKey`** — A string starting with `$` followed by at least one character (e.g., `$label.content.title`)

### Validation Rules <a href="#validation-rules" id="validation-rules"></a>

| Rule                 | Constraint                                     | Examples                                      |
| -------------------- | ---------------------------------------------- | --------------------------------------------- |
| Language code format | `^[a-z]{2}(_([a-z]{2}\|[A-Z]{2}\|[0-9]{3}))?$` | `en`, `fr`, `nl`, `en_US`, `en_GB`, `zh_Hans` |
| Label key format     | Must start with `$`                            | `$label.content.title`, `$label.defaults.cta` |

### Factory <a href="#factory" id="factory"></a>

Use the `translation.init()` factory from `@lightspeed/crane-api`:

```typescript
import { translation } from '@lightspeed/crane-api';
```

### Example <a href="#example" id="example"></a>

**`settings/translations.ts`**

```typescript
import { translation } from '@lightspeed/crane-api';

export default translation.init({
  en: {
    '$label.content.title': 'Title',
    '$label.content.title_placeholder': 'Enter a title...',
    '$label.content.description': 'Description',
    '$label.content.description_placeholder': 'Enter a description...',
    '$label.content.hero_image': 'Hero Image',
    '$label.content.cta_button': 'Call to Action',
    '$label.defaults.title': 'Welcome to Our Store',
    '$label.defaults.description': 'Discover our latest products',
    '$label.defaults.cta': 'Shop Now',
    '$label.design.title_style': 'Title Style',
    '$label.design.background': 'Background',
  },

  fr: {
    '$label.content.title': 'Titre',
    '$label.content.title_placeholder': 'Entrez un titre...',
    '$label.content.description': 'Description',
    '$label.content.description_placeholder': 'Entrez une description...',
    '$label.content.hero_image': 'Image principale',
    '$label.content.cta_button': 'Appel à l\'action',
    '$label.defaults.title': 'Bienvenue dans notre boutique',
    '$label.defaults.description': 'Découvrez nos derniers produits',
    '$label.defaults.cta': 'Acheter maintenant',
    '$label.design.title_style': 'Style du titre',
    '$label.design.background': 'Arrière-plan',
  },
});
```

### Showcase Translations <a href="#showcase-translations" id="showcase-translations"></a>

Showcases can also have their own translations in a separate `translations.ts` file inside the `showcases/` directory:

```
sections/<section-name>/showcases/
├── 1.ts
├── 2.ts
└── translations.ts
```

These translations provide localized `blockName` values and other showcase-specific text. See [Showcases](/site-themes/develop-site-themes/sections/showcases.md) for details.

### Shared Translations <a href="#shared-translations" id="shared-translations"></a>

Templates can define shared translations at the template level that apply across all sections. These are configured in the template's configuration and follow the same key/value format.

Shared translations are useful for common text that appears in multiple sections (e.g., "Read More", "Add to Cart").

### Usage in Components <a href="#usage-in-components" id="usage-in-components"></a>

Use the `useTranslation` composable to access translations in your Vue components:

```vue
<script setup lang="ts">
import { useTranslation } from '@lightspeed/crane-api';

const { t } = useTranslation();
</script>

<template>
  <h1>{{ t('$label.shared.title') }}</h1>
</template>
```

### Static vs. Merchant-Editable Text

The `useTranslation` composable reads from `shared/translation.ts` and is for **static text only** — developer-defined text that merchants cannot change.&#x20;

This is different from the `settings/translations.ts`, which provides merchant-visible labels and defaults that appear in the Instant Site Editor. For merchant-editable content, use [UI Composables](/site-themes/develop-site-themes/sections/ui-composables.md) like `useInputboxElementContent` and `useTextareaElementContent`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/sections/settings/translations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.