# Internationalization and translations

English is the official source and fallback language for AsukaDesigner v1. The runtime i18n API lets host applications override public translation keys at initialization or later at runtime.

The source of truth for built-in English strings is:

- `src/core/i18n.ts`

A generated reference list is available here:

- [Translation keys reference](./translation-keys.md)

The same list is also exported at the project root as:

- `translation_keys_with_defaults.txt`
- `translation_keys_with_defaults.json`
- `translation_keys_with_defaults_readable.txt`

## Initialization

```ts
const designer = createAsukaDesigner('#app', {
  i18n: {
    locale: 'fr',
    fallbackLocale: 'en',
    warnOnMissing: true,
    translations: {
      fr: {
        common: {
          save: 'Enregistrer',
          cancel: 'Annuler',
          close: 'Fermer',
          delete: 'Supprimer',
        },
        menu: {
          views: 'Vues',
          designs: 'Designs',
          download: 'Télécharger',
        },
      },
    },
  },
});
```

## Runtime API

```ts
designer.util.i18n.getLocale();
designer.util.i18n.setLocale('fr');
designer.util.i18n.getFallbackLocale();
designer.util.i18n.setFallbackLocale('en');
designer.util.i18n.addTranslations('fr', {
  common: { open: 'Ouvrir' },
});
designer.util.i18n.translate('common.open', 'Open');
```

## Translation resolution

When the UI asks for a key, AsukaDesigner resolves it in this order:

1. active locale dictionary
2. fallback locale dictionary
3. built-in English dictionary
4. provided fallback string
5. the key itself

`warnOnMissing: true` helps detect missing keys during integration.

`npm run i18n:scan` performs an AST-based source audit of potentially hard-coded
user-facing text. It ignores TypeScript syntax, CSS classes, tests and internal
catalog metadata so its report remains actionable.

## Nested and flat keys

The dictionary supports nested objects:

```ts
fr: {
  common: {
    save: 'Enregistrer',
  },
}
```

It also supports flat dotted keys when useful for generated translation files:

```ts
fr: {
  'common.save': 'Enregistrer',
}
```

## Menu label translations

Layout menu labels use dynamic keys.

Resolution order:

1. `menu.<id>`
2. `menu.<kind>`
3. raw `label`

Example:

```ts
const designer = createAsukaDesigner('#app', {
  layout: {
    left: {
      items: [
        { id: 'main-views', kind: 'views', label: 'Views', icon: 'views' },
      ],
    },
  },
  i18n: {
    locale: 'fr',
    translations: {
      fr: {
        menu: {
          'main-views': 'Mes vues',
          views: 'Vues',
        },
      },
    },
  },
});
```

`menu.main-views` wins for that exact item. `menu.views` is the generic fallback for every Views item.

## Main namespaces

The built-in dictionary currently includes namespaces such as:

- `common`
- `modules`
- `menu`
- `ui`
- `layout`
- `branding`
- `overlays`
- `loading`
- `download`
- `views`
- `layers`
- `designs`
- `colors`
- `image`
- `history`
- `zoom`
- `ruler`
- `magnifier`
- `text`
- `shapes`
- `elements`
- `drawingAreas`
- `fixedSlots`
- `pricing`
- `pricingRules`
- `state`
- `license`
- `studio`
- `facebook`
- `ai`

See [Translation keys reference](./translation-keys.md) for the complete list.

## Common keys to keep translated

Common action keys are reused across modules:

- `common.add`
- `common.apply`
- `common.cancel`
- `common.close`
- `common.delete`
- `common.edit`
- `common.open`
- `common.remove`
- `common.save`
- `common.search`
- `common.undo`
- `common.redo`
- `common.reset`
- `common.loading`

## Adding a new translatable UI string

When adding a UI string to the source:

1. add the key to `src/core/i18n.ts`
2. call `t('namespace.key', 'Default text')` or `getI18n().t(...)`
3. regenerate the key list if the project includes generated translation references
4. avoid hardcoded JSX text in modules unless it is technical/debug-only text

## Translator workflow

A translator can start from `translation_keys_with_defaults.json`, replace the values, and provide the result as a locale dictionary.

```ts
import fr from './fr.json';

createAsukaDesigner('#app', {
  i18n: {
    locale: 'fr',
    translations: { fr },
  },
});
```

## See also

- [Translation keys reference](./translation-keys.md)
- [Layout](./layout.md)
- [API overview](./api-overview.md)
- [Examples](./examples.md)