fantasia-i18n

name	fantasia-i18n
description	Manages vue-i18n messages and locale structure for Fantasia Archive. Use when adding or changing user-facing strings, locale files under repo-root i18n/, or markdown-backed documents wired into i18n.

Fantasia Archive — i18n

Setup

• Plugin: vue-i18n v11 (package.json ^11)
• Registry: i18n/index.ts at repo root — import app/i18n
• Types: schema/augmentation in types/vueI18nModuleAugmentation.ts; src/boot/i18n.ts side-effect-imports (may keep @ts-expect-error for TS2665) — eslint-typescript.mdc

Folder structure (i18n/en-US/)

i18n/
  index.ts
  externalFileLoader.ts
  specialCharactersFixer.ts
  _tests/
  en-US/
    index.ts
    documents/                          — .md via ?raw + specialCharacterFixer
    components/<bucket>/<ComponentName>/
    dialogs/
    floatingWindows/
    pages/
    globalFunctionality/

No locale files elsewhere. Unmatched → globalFunctionality/.

Naming: locale files L_ prefix; types elsewhere use T_.

Key naming rules

• Top-level keys from index.ts: camelCase, lowercase first (globalWindowButtons, dialogs, …)
• Sub-keys in L_*.ts: same
• index.ts: imports + composed export only — no hardcoded user strings
• documents: processed markdown only; specialCharacterFixer. Avoid literal {...} in Markdown — fantasia-changelog-en-us. No CSS rule blocks with brace delimiters — fantasia-markdown-dialogs
• Literal | in user text: \\| in TS source (Intlify escape)
• App-wide uncategorized: globalFunctionality/L_unsortedAppTexts.ts

English (en-US) capitalization

• Sentence-style: running prose, tooltips, changelog sentence refs — en-us-ui-copy-capitalization.mdc
• Headline-style: menu rows, keybind commands, dialog/floating-window titles
• appControlMenus top four title strings: menu-bar title casing
• Other locales: mirror semantic roles, not English caps

index.ts rules

• Imports + export object only
• Import order: markdown documents → components/ → dialogs/ → floatingWindows/ → globalFunctionality/ → pages/

Using strings in code

• Vue templates: $t('camelCaseKey.subKey')
• TS / Pinia: import { i18n } from 'app/i18n/externalFileLoader' → i18n.global.t(...)
• No hardcoded user prose in .vue, _data/, scripts

Tests tied to copy changes

Key changes affecting toHaveText, aria-label, L_* in Playwright → grep + run matching Vitest/Playwright; rebuild Electron when bundle matters — fantasia-testing.

Adding new strings

1. Pick folder (components/, dialogs/, pages/, globalFunctionality/)
2. Create/edit L_<name>.ts
3. Import in index.ts → new camelCase top-level key
4. Use full dot-path in $t / i18n.global.t
5. Mirror in other locales when maintained

Storybook integration

• Import focused L_* modules — not i18n/en-US/index.ts (pulls markdown)
• Placeholder documents.* in externalFileLoader.ts
• Mandatory: new L_* in i18n/en-US/index.ts used by stories → same PR adds import + key to defaultMessages

Related

• en-us-ui-copy-capitalization.mdc
• fantasia-testing
• fantasia-markdown-dialogs

Types

Shared types → types/. See types-folder.mdc.