i18n

Mango Internationalization & Languages

Mango provides built-in internationalization (i18n) support, allowing developers to localize both user interface controls and dynamic metadata.

---

1. Supported Languages

Mango currently supports four languages:

• English (en) (Default)
• Spanish (es)
• Welsh (cy)
• French (fr)

The raw translation JSON files are stored in the src/locales directory:

• en.json
• es.json
• cy.json
• fr.json

---

2. i18n Architecture

The translation pipeline is handled in src/lib/core/i18n.ts. It exports the following APIs:

The Locale Store

• locale: A writable Svelte store containing the active locale string (e.g. 'cy').
• setLocale(value: string): Normalises and sets the active locale. It falls back to 'en' if the requested locale is unsupported.
• getLocale(): Synchronously retrieves the current locale string.

The Translate API

• translate(key: string, params?: Record<string, string | number>, overrideLocale?: string):
  • Looks up the dot-notation key (e.g. plugins.hello.label) inside the target locale's JSON.
  • Formats variables matching the {variableName} syntax.
• t: A derived Svelte store providing a reactive lookup handler inside Svelte components.

---

3. Usage Examples

Within Svelte Components

<script lang="ts">
  import { t } from '../core/i18n';
</script>

<div class="header">
  <h2>{$t('viewer.gallery.canvasAlt', { index: 1 })}</h2>
  <button>{$t('viewer.controls.close')}</button>
</div>

Within TypeScript Files

import { translate } from '../core/i18n';

console.log(translate('warnings.pluginMissingId'));

---

4. How to Add a New Locale

1. Create the translation file: Create a new JSON file under src/locales/ (e.g., de.json for German). Copy the keys from en.json and translate the values.
2. Register the file in i18n.ts: Import the JSON and append it to the catalogue:

   import de from '../../locales/de.json';
   
   const catalogue = {
     en,
     es,
     cy,
     fr,
     de, // Register here
   };

3. Validation: Run translation checks to verify all translation keys are present across JSON catalogues.