국제화

UI 문자열은 Paraglide JS를 거칩니다. 빌드 시점에 messages/<locale>.json을 타입이 있는 함수로 컴파일합니다.

import * as m from '$lib/paraglide/messages';
m.some_key();

이는 운영자용 다국어 설정 값(DESCRIPTION, TOPBAR.TITLE, …)과는 별개입니다. 후자는 런타임에 resolveI18nValue()가 해석합니다.

규칙

키 형식은 밑줄_구분입니다. menu.graphPanel이 아니라 menu_graph_panel입니다.
src/lib/paraglide/의 생성된 코드는 절대 손으로 수정하지 않으며, gitignore 대상입니다.
로케일은 project.inlang/settings.json(baseLocale + locales)에 등록합니다. Vite 플러그인이 개발·빌드·테스트 시 src/lib/paraglide/를 다시 생성합니다.
언어 전환은 $lib/paraglide/runtime의 setLocale('ko')로 합니다(getLocale, locales도 함께 제공됩니다).

npm run check는 Vite를 거치지 않으므로, 갓 클론한 상태에서는 $lib/paraglide/*에 타입 선언이 없습니다. 그래서 check는 먼저 npm run i18n:compile을 실행합니다. Vite 플러그인과 동일한 옵션을 쓰는 Paraglide CLI이므로 둘을 같은 상태로 유지하세요. prepare도 이를 실행하므로, 단순히 npm ci만 해도 타입 검사가 가능한 트리가 됩니다.

언어 추가하기

project.inlang/settings.json의 locales에 로케일 코드를 추가합니다.
messages/<locale>.json을 만듭니다.

이것으로 끝입니다. MiscPanel의 언어 선택기가 locales를 읽고 Intl.DisplayNames로 이름을 붙이므로 컴포넌트를 수정할 필요가 없습니다. 키는 시간이 지나며 채워집니다. 위의 폴백 안내를 참고하세요.

번역 기여 흐름

번역자는 messages/<locale>.json을 직접 건드리지 않습니다. 아직 작업이 필요한 키만 담긴, 생성된 스테이징 파일을 수정합니다.

명령어	대상	설명
`npm run i18n:check`	누구나	로케일별로 누락되거나 오래된 키를 보고합니다. 아무것도 변경하지 않습니다.
`npm run i18n:missing`	메인테이너	`messages/_missing_translations_<locale>.json`을 생성합니다. 빠진 키를 `en` 원문으로 채워 둡니다.
`npm run i18n:apply`	메인테이너	스테이징 파일을 `messages/<locale>.json`에 병합하고(`en` 키 순서로) 스테이징 파일을 삭제합니다.

messages/en.json에 키가 추가되면 → npm run i18n:missing으로 스테이징 파일을 다시 생성합니다.
번역자가 messages/_missing_translations_ko.json을 수정하고 PR을 엽니다. 확신이 서지 않는 키는 아예 빼도 됩니다. 그런 키는 계속 영어로 폴백됩니다.
PR을 병합한 뒤 npm run i18n:apply를 실행하고 결과를 커밋합니다.

i18n:apply는 en.json에 없는 키와 비워 둔 키를 건너뛰며, 오래된 키는 제거하지 않고 보존합니다. 미리 확인하려면 --dry-run을 사용하세요.

Paraglide는 _missing_translations_*.json을 무시합니다. project.inlang/settings.json에 나열된 로케일만 컴파일합니다.

Frequency Tutorial 텍스트

Frequency Tutorial 오버레이의 라벨은 일반 UI 문자열입니다. 대역마다 _name / _desc 한 쌍이 있으며, 키 이름은 tutorial_freq_<band>_name과 tutorial_freq_<band>_desc입니다. 대역은 sub_bass, bass, lower_mids, upper_mids, presence, brilliance입니다.

{
  "tutorial_freq_sub_bass_name": "Sub Bass",
  "tutorial_freq_sub_bass_desc": "The Rumble, usually out of human's hearing range...",
  "tutorial_freq_bass_name": "Bass",
  "tutorial_freq_bass_desc": "Determines how 'fat' or 'thin' the sound is..."
}

번들에 컴파일되어 들어가므로 CDN이나 사전 빌드 릴리스로 운영하는 경우에는 바꿀 수 없습니다. 문구를 고치려면 소스에서 빌드하거나 PR을 보내야 합니다.