feat: localized instrument catalogs

README.md

@@ -45,11 +45,36 @@ interface Instrument {
 }
 ```
 
+## Localized names
+
+`data/instruments.json` carries English names. Every other locale is available as a **complete,
+drop-in catalog** with the exact same shape under `data/i18n/<lang>.json` — every group and
+instrument is present, with localized `name` and `shortname` (falling back to English wherever no
+translation exists). You load the one file for the locale you need; there is nothing to merge.
+
+```ts
+import type { InstrumentsFile } from '@flat/instruments';
+import fr from '@flat/instruments/data/i18n/fr.json' with { type: 'json' };
+
+const catalog = fr as InstrumentsFile;
+catalog.groups[0].name;                                       // → "Cuivres"
+catalog.groups
+  .flatMap(g => g.instruments)
+  .find(i => i.id === 'brass.trumpet');                       // → { …, name: "Trompette", shortname: "Tromp." }
+```
+
+Available locales: `da`, `de`, `en-GB`, `es`, `fi`, `fil`, `fr`, `fr-CA`, `hi`, `id`, `it`, `ja`,
+`ja-HIRA`, `ko`, `ms`, `nb`, `nl`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sv`, `tr`, `zh-Hans`, `zh-HK`,
+`zh-TW`. Each file validates against the same
+[`schema/instruments.schema.json`](./schema/instruments.schema.json) and exposes the same instrument
+IDs, in the same order, as `data/instruments.json` — only the names differ.
+
 ## Raw JSON
 
 If you are not using JavaScript, the same data is available as plain JSON, bundled in this package at
-[`data/instruments.json`](./data/instruments.json)
-(validated against [`schema/instruments.schema.json`](./schema/instruments.schema.json)).
+[`data/instruments.json`](./data/instruments.json) (English) and
+[`data/i18n/<lang>.json`](./data/i18n) (localized), both validated against
+[`schema/instruments.schema.json`](./schema/instruments.schema.json).
 
 ## Development