wehub-resource-sync
111 lines
3.3 KiB
Plaintext
111 lines
3.3 KiB
Plaintext
---
|
|
title: Locale
|
|
description: Translate the runtime UI — home, inspector, presenter, toasts.
|
|
---
|
|
|
|
The runtime ships with four built-in dictionaries. Switch between them from
|
|
the language picker in the slide UI (next to the theme toggle) — your choice
|
|
is remembered in the browser.
|
|
|
|
The locale only affects the **runtime UI** that open-slide renders around
|
|
your slides (the home screen, slide browser, inspector, asset panel,
|
|
presenter mode, toasts, etc.). It does **not** translate slide content —
|
|
that lives in your own React code.
|
|
|
|
## Picking a language
|
|
|
|
Open the language picker in the top-right of the home sidebar and choose one
|
|
of the four built-in languages. The selection is saved locally and applies
|
|
across the runtime UI.
|
|
|
|
## Presets
|
|
|
|
| Import | `id` | Language |
|
|
| -------- | --------- | ------------------- |
|
|
| `en` | `'en'` | English (default) |
|
|
| `zhTW` | `'zh-TW'` | 繁體中文 |
|
|
| `zhCN` | `'zh-CN'` | 简体中文 |
|
|
| `ja` | `'ja'` | 日本語 |
|
|
|
|
All presets are re-exported from the `@open-slide/core/locale` subpath:
|
|
|
|
```ts
|
|
import { en, zhTW, zhCN, ja } from '@open-slide/core/locale';
|
|
```
|
|
|
|
Until a language is picked in the UI, the runtime defaults to `en`.
|
|
|
|
## The deprecated `locale` config
|
|
|
|
<Callout type="warn">
|
|
`config.locale` is **deprecated** — use the in-UI language picker instead.
|
|
When set, it only seeds the initial language until the user picks one.
|
|
</Callout>
|
|
|
|
```ts title="open-slide.config.ts"
|
|
import type { OpenSlideConfig } from '@open-slide/core';
|
|
import { zhTW } from '@open-slide/core/locale';
|
|
|
|
const config: OpenSlideConfig = {
|
|
locale: zhTW,
|
|
};
|
|
|
|
export default config;
|
|
```
|
|
|
|
## Custom dictionaries
|
|
|
|
A locale is plain data — no functions, no JSX — so it serializes through
|
|
the build cleanly. Provide your own object as long as it matches the
|
|
`Locale` type from `@open-slide/core`.
|
|
|
|
```ts title="open-slide.config.ts"
|
|
import type { OpenSlideConfig, Locale } from '@open-slide/core';
|
|
import { en } from '@open-slide/core/locale';
|
|
|
|
const fr: Locale = {
|
|
...en,
|
|
id: 'en', // pick the closest built-in id
|
|
common: {
|
|
...en.common,
|
|
save: 'Enregistrer',
|
|
cancel: 'Annuler',
|
|
// …override the rest
|
|
},
|
|
};
|
|
|
|
const config: OpenSlideConfig = { locale: fr };
|
|
export default config;
|
|
```
|
|
|
|
The `id` field today only has to be one of the built-in ids
|
|
(`'en' | 'zh-TW' | 'zh-CN' | 'ja'`); it is reserved for future locale-aware
|
|
formatting. The dictionary keys are what actually drive the UI.
|
|
|
|
The full shape lives in `packages/core/src/locale/types.ts` — start from a
|
|
preset and override the keys you need rather than building one from scratch.
|
|
|
|
## Templates and plurals
|
|
|
|
A few entries are templates with `{name}`-style placeholders, or plural
|
|
forms (`{ one, other }`). They are flagged in the type definition with
|
|
JSDoc, e.g.:
|
|
|
|
```ts
|
|
/** template: "Loading {slideId}…" */
|
|
loadingSlide: string;
|
|
|
|
/** templates: "{count} unsaved change" / "{count} unsaved changes" */
|
|
unsavedChanges: Plural;
|
|
```
|
|
|
|
The runtime expands these for you — your job is just to keep the same
|
|
`{placeholder}` tokens (and both `one` and `other` forms) when translating.
|
|
|
|
## Notes
|
|
|
|
- Locale is read at module init. Changing it requires a dev-server reload
|
|
or a fresh build.
|
|
- There is no in-app language switcher today; pick a single locale per
|
|
deployment.
|