@zerwiz/ymir 0.1.34 → 0.1.35

package/apps/sessrumnir/src/shared/i18n/index.test.ts

@@ -0,0 +1,51 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { availableLanguages, i18n, languageNativeName, t } from './index'
+import { PSEUDO_LANGUAGE, SOURCE_LANGUAGE } from './languages'
+
+const EMPTY_TEST_LANGUAGE = 'xx'
+const NAMESPACE = 'translation'
+
+test('the shared instance starts in English with the bundled resources', () => {
+  assert.equal(i18n.isInitialized, true)
+  assert.equal(i18n.language, SOURCE_LANGUAGE)
+  assert.equal(t('language.nativeName'), 'English')
+})
+
+test('availableLanguages adds the pseudo-language only when enabled', () => {
+  assert.deepEqual(availableLanguages(false), [SOURCE_LANGUAGE])
+  assert.deepEqual(availableLanguages(true), [SOURCE_LANGUAGE, PSEUDO_LANGUAGE])
+})
+
+test('an empty translation falls back to English', () => {
+  i18n.addResourceBundle(EMPTY_TEST_LANGUAGE, NAMESPACE, { language: { nativeName: '' } })
+  try {
+    assert.equal(languageNativeName(EMPTY_TEST_LANGUAGE), 'English')
+  } finally {
+    i18n.removeResourceBundle(EMPTY_TEST_LANGUAGE, NAMESPACE)
+  }
+})
+
+test('the pseudo-language marks text but not explicit English lookups', async () => {
+  await i18n.changeLanguage(PSEUDO_LANGUAGE)
+  try {
+    assert.equal(t('language.nativeName'), '[Éñĝļîšĥ ~~~]')
+    assert.equal(t('language.nativeName', { lng: SOURCE_LANGUAGE }), 'English')
+    assert.equal(languageNativeName(PSEUDO_LANGUAGE), '[Éñĝļîšĥ ~~~]')
+  } finally {
+    await i18n.changeLanguage(SOURCE_LANGUAGE)
+  }
+})
+
+test('the pseudo-language bundle leaves interpolated values unmarked', async () => {
+  await i18n.changeLanguage(PSEUDO_LANGUAGE)
+  try {
+    // The placeholder is substituted after lookup, so the pseudo-localized
+    // sentence around it is marked but the inserted value is plain English.
+    assert.match(t('settings.language.system', { language: 'English' }), /\(English\)/)
+    // An explicit English lookup is never pseudo-localized.
+    assert.equal(t('settings.language.label', { lng: SOURCE_LANGUAGE }), 'Language')
+  } finally {
+    await i18n.changeLanguage(SOURCE_LANGUAGE)
+  }
+})

package/apps/sessrumnir/src/shared/i18n/index.ts

@@ -0,0 +1,50 @@
+import i18next, { type TFunction } from 'i18next'
+import { BUNDLED_LANGUAGES, LANGUAGE_RESOURCES } from './resources'
+import { PSEUDO_LANGUAGE, SOURCE_LANGUAGE } from './languages'
+import { pseudoLocalizeTree } from './pseudo'
+
+const NAMESPACE = 'translation'
+
+// One instance per process (main, renderer, and each test process). Init is
+// synchronous because the resources are bundled, so t() works as soon as this
+// module is imported, always starting in English.
+//
+// The pseudo-language is a generated resource bundle, not a post-processor
+// run on every t() result: a post-processor runs after interpolation, so it
+// would also mangle already-substituted placeholder values and mark English
+// text pulled in via an explicit { lng: 'en' } lookup. Generating the bundle
+// once here, from the English tree, keeps placeholders and explicit English
+// lookups untouched — only the English text itself is pseudo-localized.
+if (!i18next.isInitialized) {
+  void i18next.init({
+    resources: {
+      ...LANGUAGE_RESOURCES,
+      [PSEUDO_LANGUAGE]: { translation: pseudoLocalizeTree(LANGUAGE_RESOURCES.en.translation) },
+    },
+    lng: SOURCE_LANGUAGE,
+    fallbackLng: SOURCE_LANGUAGE,
+    defaultNS: NAMESPACE,
+    initAsync: false,
+    // An empty value means "not translated yet" and must show English.
+    returnEmptyString: false,
+    // React escapes output; menus, dialogs, and notifications are not HTML.
+    interpolation: { escapeValue: false },
+  })
+}
+
+export const i18n = i18next
+export const t = i18next.t
+/** English whatever the interface language: for logs and the diagnostics report, which stay English. */
+export const tEnglish = i18next.getFixedT(SOURCE_LANGUAGE)
+/** A translator: `t` for interface text, `tEnglish` for logs and the diagnostics report. */
+export type Translate = TFunction
+
+/** Codes the Language picker offers. The pseudo-language only when enabled. */
+export function availableLanguages(pseudoEnabled: boolean): string[] {
+  return pseudoEnabled ? [...BUNDLED_LANGUAGES, PSEUDO_LANGUAGE] : [...BUNDLED_LANGUAGES]
+}
+
+/** A language's own name ("Deutsch"), as its translator wrote it. */
+export function languageNativeName(code: string): string {
+  return i18next.t('language.nativeName', { lng: code })
+}

package/apps/sessrumnir/src/shared/i18n/languages.ts

@@ -0,0 +1,12 @@
+/** The language every other language file is translated from. */
+export const SOURCE_LANGUAGE = 'en'
+
+/** Test language that marks every translated string (see pseudo.ts). */
+export const PSEUDO_LANGUAGE = 'en-XA'
+
+/** `language` setting value that follows the OS language list. */
+export const SYSTEM_LANGUAGE = 'system'
+
+/** Env var that makes the pseudo-language selectable in any build. */
+export const PSEUDO_LANGUAGE_ENV = 'PI_DESKTOP_PSEUDO_LANGUAGE'
+export const PSEUDO_LANGUAGE_ENV_ON = '1'

package/apps/sessrumnir/src/shared/i18n/locale-checks.ts

@@ -0,0 +1,98 @@
+import { SOURCE_LANGUAGE } from './languages'
+
+export type LocaleTree = { [key: string]: string | LocaleTree }
+
+const PLURAL_CATEGORIES = ['zero', 'one', 'two', 'few', 'many', 'other'] as const
+const PLURAL_SUFFIX = new RegExp(`_(${PLURAL_CATEGORIES.join('|')})$`)
+// {{name}} and {{name, format}} both name the value "name".
+const PLACEHOLDER = /\{\{\s*([^,}\s]+)[^}]*\}\}/g
+// <link>, </link>, <1/>: the tag name is what <Trans> matches on.
+const TAG = /<\/?([A-Za-z0-9]+)\s*\/?>/g
+const NATIVE_NAME_KEY = 'language.nativeName'
+const NO_FORM = ''
+
+export function flattenLocale(tree: LocaleTree, prefix = ''): Map<string, string> {
+  const flat = new Map<string, string>()
+  for (const [key, value] of Object.entries(tree)) {
+    const path = prefix ? `${prefix}.${key}` : key
+    if (typeof value === 'string') flat.set(path, value)
+    else for (const [nestedKey, nestedValue] of flattenLocale(value, path)) flat.set(nestedKey, nestedValue)
+  }
+  return flat
+}
+
+// base key -> (plural category, or NO_FORM for a plain key) -> text
+function groupByBase(flat: Map<string, string>): Map<string, Map<string, string>> {
+  const groups = new Map<string, Map<string, string>>()
+  for (const [key, text] of flat) {
+    const match = key.match(PLURAL_SUFFIX)
+    const base = match ? key.slice(0, -match[0].length) : key
+    const form = match ? match[1] : NO_FORM
+    if (!groups.has(base)) groups.set(base, new Map())
+    groups.get(base)!.set(form, text)
+  }
+  return groups
+}
+
+function namesIn(text: string, pattern: RegExp): Set<string> {
+  return new Set([...text.matchAll(pattern)].map((match) => match[1]))
+}
+
+function sameSet(a: Set<string>, b: Set<string>): boolean {
+  return a.size === b.size && [...a].every((item) => b.has(item))
+}
+
+function sorted(set: Set<string>): string {
+  return [...set].sort().join(', ')
+}
+
+/**
+ * Problems in one language file compared with English. A translation may
+ * leave a value empty (the app then shows English); English may not.
+ */
+export function checkLocale(language: string, tree: LocaleTree, english: LocaleTree): string[] {
+  const problems: string[] = []
+  const englishGroups = groupByBase(flattenLocale(english))
+  const flat = flattenLocale(tree)
+  const groups = groupByBase(flat)
+  const pluralCategories = new Set<string>(new Intl.PluralRules(language).resolvedOptions().pluralCategories)
+
+  for (const base of englishGroups.keys()) {
+    if (!groups.has(base)) problems.push(`${language}: missing key ${base}`)
+  }
+
+  for (const [base, forms] of groups) {
+    const englishForms = englishGroups.get(base)
+    if (!englishForms) {
+      problems.push(`${language}: unknown key ${base}`)
+      continue
+    }
+
+    const isPlural = !englishForms.has(NO_FORM)
+    const formNames = new Set(forms.keys())
+    if (isPlural && !sameSet(formNames, pluralCategories)) {
+      problems.push(`${language}: ${base} needs plural forms ${sorted(pluralCategories)}`)
+    } else if (!isPlural && (formNames.size !== 1 || !formNames.has(NO_FORM))) {
+      problems.push(`${language}: ${base} must not have plural forms`)
+    }
+
+    const englishText = [...englishForms.values()].join(' ')
+    const allowedPlaceholders = namesIn(englishText, PLACEHOLDER)
+    const englishTags = namesIn(englishText, TAG)
+    for (const [form, text] of forms) {
+      const key = form === NO_FORM ? base : `${base}_${form}`
+      if (text === '') {
+        if (language === SOURCE_LANGUAGE || key === NATIVE_NAME_KEY) problems.push(`${language}: ${key} is empty`)
+        continue
+      }
+      for (const name of namesIn(text, PLACEHOLDER)) {
+        if (!allowedPlaceholders.has(name)) problems.push(`${language}: ${key} uses unknown placeholder {{${name}}}`)
+      }
+      if (!sameSet(namesIn(text, TAG), englishTags)) {
+        problems.push(`${language}: ${key} must keep the tags ${sorted(englishTags)}`)
+      }
+    }
+  }
+
+  return problems
+}

package/apps/sessrumnir/src/shared/i18n/locales.test.ts

@@ -0,0 +1,92 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { checkLocale, type LocaleTree } from './locale-checks'
+import { BUNDLED_LANGUAGES, LANGUAGE_RESOURCES } from './resources'
+import { SOURCE_LANGUAGE } from './languages'
+
+const LOCALES_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'resources', 'locales')
+
+const ENGLISH: LocaleTree = {
+  language: { nativeName: 'English' },
+  files: { count_one: 'One file', count_other: '{{count}} files' },
+  help: 'See <link>docs</link> for {{topic}}',
+}
+
+test('the bundled English file passes', () => {
+  const english = LANGUAGE_RESOURCES.en.translation as LocaleTree
+  assert.deepEqual(checkLocale(SOURCE_LANGUAGE, english, english), [])
+})
+
+test('every locale folder is imported into BUNDLED_LANGUAGES', () => {
+  const folders = readdirSync(LOCALES_DIR, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+  assert.deepEqual([...BUNDLED_LANGUAGES].sort(), folders)
+})
+
+test('every bundled language passes', () => {
+  const english = LANGUAGE_RESOURCES.en.translation as LocaleTree
+  for (const code of BUNDLED_LANGUAGES) {
+    const tree = LANGUAGE_RESOURCES[code as keyof typeof LANGUAGE_RESOURCES].translation as LocaleTree
+    assert.deepEqual(checkLocale(code, tree, english), [], code)
+  }
+})
+
+test('English may not have empty values', () => {
+  const english: LocaleTree = { ...ENGLISH, help: '' }
+  assert.deepEqual(checkLocale('en', english, english), ['en: help is empty'])
+})
+
+test('a translation may leave values empty', () => {
+  const german: LocaleTree = {
+    language: { nativeName: 'Deutsch' },
+    files: { count_one: '', count_other: '' },
+    help: '',
+  }
+  assert.deepEqual(checkLocale('de', german, ENGLISH), [])
+})
+
+test('missing and unknown keys are reported', () => {
+  const german: LocaleTree = {
+    language: { nativeName: 'Deutsch' },
+    files: { count_one: 'Eine Datei', count_other: '{{count}} Dateien' },
+    extra: 'x',
+  }
+  assert.deepEqual(checkLocale('de', german, ENGLISH), ['de: missing key help', 'de: unknown key extra'])
+})
+
+test('plural keys must match the language plural categories', () => {
+  const russian: LocaleTree = {
+    language: { nativeName: 'Русский' },
+    files: { count_one: '{{count}} файл', count_other: '{{count}} файла' },
+    help: 'См. <link>документацию</link> о {{topic}}',
+  }
+  assert.deepEqual(checkLocale('ru', russian, ENGLISH), ['ru: files.count needs plural forms few, many, one, other'])
+  const chinese: LocaleTree = {
+    language: { nativeName: '简体中文' },
+    files: { count_other: '{{count}} 个文件' },
+    help: '参见 <link>文档</link> 了解 {{topic}}',
+  }
+  assert.deepEqual(checkLocale('zh-Hans', chinese, ENGLISH), [])
+})
+
+test('unknown placeholders and changed tags are reported', () => {
+  const german: LocaleTree = {
+    language: { nativeName: 'Deutsch' },
+    files: { count_one: 'Eine Datei', count_other: '{{total}} Dateien' },
+    help: 'Siehe Doku zu {{topic}}',
+  }
+  assert.deepEqual(checkLocale('de', german, ENGLISH), [
+    'de: files.count_other uses unknown placeholder {{total}}',
+    'de: help must keep the tags link',
+  ])
+})
+
+test('the native name may not be empty', () => {
+  const german: LocaleTree = { ...ENGLISH, language: { nativeName: '' } }
+  assert.deepEqual(checkLocale('de', german, ENGLISH), ['de: language.nativeName is empty'])
+})

package/apps/sessrumnir/src/shared/i18n/pseudo.test.ts

@@ -0,0 +1,39 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { pseudoLocalize, pseudoLocalizeTree } from './pseudo'
+
+test('adds accents, about 35% padding, and brackets', () => {
+  assert.equal(pseudoLocalize('Settings'), '[Šéţţîñĝš ~~~]')
+})
+
+test('keeps placeholders and tags unchanged', () => {
+  assert.equal(pseudoLocalize('Hi {{name}}'), '[Ĥî {{name}} ~~~~]')
+  assert.equal(pseudoLocalize('See <link>docs</link>'), '[Šéé <link>ðöçš</link> ~~~~~~~~]')
+})
+
+test('leaves digits, punctuation, and non-Latin text as they are', () => {
+  assert.equal(pseudoLocalize('3.5%'), '[3.5% ~~]')
+})
+
+test('returns an empty string unchanged', () => {
+  assert.equal(pseudoLocalize(''), '')
+})
+
+test('pseudoLocalizeTree pseudo-localizes every string leaf', () => {
+  const tree = {
+    settings: { title: 'Settings' },
+    count_one: '{{count}} item',
+    count_other: '{{count}} items',
+  }
+  const result = pseudoLocalizeTree(tree)
+  assert.equal(result.settings.title, pseudoLocalize('Settings'))
+  assert.equal(result.count_one, pseudoLocalize('{{count}} item'))
+  assert.equal(result.count_other, pseudoLocalize('{{count}} items'))
+})
+
+test('pseudoLocalizeTree keeps keys, including plural suffixes, unchanged', () => {
+  const tree = { count_one: 'a', count_other: 'b', nested: { label: 'c' } }
+  const result = pseudoLocalizeTree(tree)
+  assert.deepEqual(Object.keys(result), Object.keys(tree))
+  assert.deepEqual(Object.keys(result.nested), Object.keys(tree.nested))
+})

package/apps/sessrumnir/src/shared/i18n/pseudo.ts

@@ -0,0 +1,44 @@
+import type { LocaleTree } from './locale-checks'
+
+const ACCENTED: Readonly<Record<string, string>> = {
+  a: 'á', b: 'ƀ', c: 'ç', d: 'ð', e: 'é', f: 'ƒ', g: 'ĝ', h: 'ĥ', i: 'î', j: 'ĵ', k: 'ķ', l: 'ļ', m: 'ɱ',
+  n: 'ñ', o: 'ö', p: 'þ', q: 'ǫ', r: 'ŕ', s: 'š', t: 'ţ', u: 'û', v: 'ṽ', w: 'ŵ', x: 'ẋ', y: 'ý', z: 'ž',
+  A: 'Á', B: 'Ɓ', C: 'Ç', D: 'Ð', E: 'É', F: 'Ƒ', G: 'Ĝ', H: 'Ĥ', I: 'Î', J: 'Ĵ', K: 'Ķ', L: 'Ļ', M: 'Ṁ',
+  N: 'Ñ', O: 'Ö', P: 'Þ', Q: 'Ǫ', R: 'Ŕ', S: 'Š', T: 'Ţ', U: 'Û', V: 'Ṽ', W: 'Ŵ', X: 'Ẋ', Y: 'Ý', Z: 'Ž',
+}
+
+// Placeholders and <Trans> tags must survive so interpolation and rich text
+// still work. split() with a capture group keeps them at odd indexes.
+const PROTECTED_PARTS = /(\{\{[^}]*\}\}|<[^>]*>)/
+// Longer languages (German, Finnish) run about 35% longer than English.
+const EXPANSION_RATIO = 0.35
+const PADDING_CHAR = '~'
+
+/**
+ * Test-language form of a string: "Settings" becomes "[Šéţţîñĝš ~~~]".
+ * Text on screen without brackets was never translated; cut-off text shows
+ * where a longer language breaks the layout.
+ */
+export function pseudoLocalize(text: string): string {
+  if (text === '') return text
+  const accented = text
+    .split(PROTECTED_PARTS)
+    .map((part, index) => (index % 2 === 1 ? part : [...part].map((char) => ACCENTED[char] ?? char).join('')))
+    .join('')
+  const padding = PADDING_CHAR.repeat(Math.ceil(text.length * EXPANSION_RATIO))
+  return `[${accented} ${padding}]`
+}
+
+/**
+ * Deep copy of a locale tree with every string value run through
+ * `pseudoLocalize`. Keys are left exactly as they are, so plural suffixes
+ * (`_one`, `_other`) and context variants (`_global`, `_workspace`) keep
+ * matching the code that looks them up.
+ */
+export function pseudoLocalizeTree<T extends LocaleTree>(tree: T): T {
+  const result: LocaleTree = {}
+  for (const [key, value] of Object.entries(tree)) {
+    result[key] = typeof value === 'string' ? pseudoLocalize(value) : pseudoLocalizeTree(value)
+  }
+  return result as T
+}

package/apps/sessrumnir/src/shared/i18n/resolve.test.ts

@@ -0,0 +1,43 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { normalizeLanguageSetting, resolveLanguage } from './resolve'
+
+const AVAILABLE = ['en', 'de', 'pt-BR', 'zh-Hans', 'zh-Hant']
+
+test('an explicit available setting wins over the system languages', () => {
+  assert.equal(resolveLanguage('de', ['pt-BR'], AVAILABLE), 'de')
+})
+
+test('system setting takes an exact match, case-insensitive', () => {
+  assert.equal(resolveLanguage('system', ['PT-br'], AVAILABLE), 'pt-BR')
+})
+
+test('system setting falls back from a region to the same language', () => {
+  assert.equal(resolveLanguage('system', ['de-AT'], AVAILABLE), 'de')
+})
+
+test('system setting maps Chinese regions to the matching script', () => {
+  assert.equal(resolveLanguage('system', ['zh-TW'], AVAILABLE), 'zh-Hant')
+  assert.equal(resolveLanguage('system', ['zh-CN'], AVAILABLE), 'zh-Hans')
+})
+
+test('system languages are tried in order', () => {
+  assert.equal(resolveLanguage('system', ['fr-FR', 'de-DE', 'en-US'], AVAILABLE), 'de')
+})
+
+test('no match and invalid tags resolve to English', () => {
+  assert.equal(resolveLanguage('system', ['fr-FR', 'not a tag!'], AVAILABLE), 'en')
+  assert.equal(resolveLanguage('system', [], AVAILABLE), 'en')
+})
+
+test('a setting that is not available follows the system languages', () => {
+  assert.equal(resolveLanguage('fr', ['de-DE'], AVAILABLE), 'de')
+})
+
+test('normalizeLanguageSetting keeps available codes and resets the rest to system', () => {
+  assert.equal(normalizeLanguageSetting('de', AVAILABLE), 'de')
+  assert.equal(normalizeLanguageSetting('system', AVAILABLE), 'system')
+  assert.equal(normalizeLanguageSetting('fr', AVAILABLE), 'system')
+  assert.equal(normalizeLanguageSetting(42, AVAILABLE), 'system')
+  assert.equal(normalizeLanguageSetting(undefined, AVAILABLE), 'system')
+})

package/apps/sessrumnir/src/shared/i18n/resolve.ts

@@ -0,0 +1,41 @@
+import { SOURCE_LANGUAGE, SYSTEM_LANGUAGE } from './languages'
+
+// "zh-TW" and "zh-Hant" both maximize to "zh-Hant"; "de-AT" and "de" both to
+// "de-Latn". Comparing this pair matches a region to the file for its
+// language without mixing up scripts. Returns null for a tag Intl rejects.
+function languageAndScript(tag: string): string | null {
+  try {
+    const locale = new Intl.Locale(tag).maximize()
+    return `${locale.language}-${locale.script ?? ''}`
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The language code the app shows. An explicit available setting wins; the
+ * 'system' setting (or a code no longer available) takes the first OS
+ * language with an exact match, then the first with the same language and
+ * script; anything else is English.
+ */
+export function resolveLanguage(
+  setting: string,
+  systemLanguages: readonly string[],
+  available: readonly string[],
+): string {
+  if (setting !== SYSTEM_LANGUAGE && available.includes(setting)) return setting
+  for (const tag of systemLanguages) {
+    const exact = available.find((code) => code.toLowerCase() === tag.toLowerCase())
+    if (exact) return exact
+    const wanted = languageAndScript(tag)
+    if (!wanted) continue
+    const sameScript = available.find((code) => languageAndScript(code) === wanted)
+    if (sameScript) return sameScript
+  }
+  return SOURCE_LANGUAGE
+}
+
+/** The stored `language` setting, reset to 'system' when it is not an available code. */
+export function normalizeLanguageSetting(value: unknown, available: readonly string[]): string {
+  return typeof value === 'string' && available.includes(value) ? value : SYSTEM_LANGUAGE
+}

package/apps/sessrumnir/src/shared/i18n/resources.ts

@@ -0,0 +1,11 @@
+import en from '../../../resources/locales/en/translation.json'
+
+/**
+ * Every bundled language. To add a language, import its
+ * resources/locales/<code>/translation.json here and add one entry.
+ */
+export const LANGUAGE_RESOURCES = {
+  en: { translation: en },
+} as const
+
+export const BUNDLED_LANGUAGES: string[] = Object.keys(LANGUAGE_RESOURCES)