lino-i18n 0.0.1 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # lino-i18n Changelog
 
+## 0.1.1
+
+### Patch Changes
+
+- 22cf52e: Document the Hive Mind deep catalogue authoring pattern and keep JS examples aligned.
+
+## 0.1.0
+
+### Minor Changes
+
+- 4c3b133: Add configurable compatibility aliases for deeper nested migration keys.
+
+## 0.0.2
+
+### Patch Changes
+
+- 29f0d6f: Preserve scalar parent translations as `label` children when formatting nested
+  catalogues, and resolve `foo` from `foo.label` when no explicit `foo`
+  translation exists.
+
 ## 0.0.1
 
 Initial release of the JavaScript `lino-i18n` package.

package/README.md

@@ -30,6 +30,7 @@ i18n.t('greeting', { name: 'World' }); // → "Hello, World!"
 i18n.t('cart.items', { count: 0 }); // → "Your cart is empty"
 i18n.t('cart.items', { count: 3 }, { locale: 'ru' }); // → "3 товара"
 i18n.t('role', { context: 'female' }); // → "She is a developer"
+i18n.t('telegram.help.solve.alias.detail'); // → "Tool aliases imply `--tool <tool>`"
 ```
 
 A sample `.lino` catalogue looks like this:
@@ -37,11 +38,26 @@ A sample `.lino` catalogue looks like this:
 ```lino
 en
   greeting "Hello, {{name}}!"
-  hero
-    description """
-      Keep each language in its own block, nest related messages together,
-      and still resolve the same runtime keys.
-    """
+  telegram
+    help
+      title "Help"
+      solve
+        alias
+          detail "Tool aliases imply `--tool <tool>`"
+  prompt
+    system
+      general
+        guidelines
+          header "General guidelines."
+          body """
+            When you start, create a detailed plan for yourself.
+            Follow your todo list step by step.
+          """
+  error
+    label "Error"
+    invalid
+      github
+        url "Error: Invalid GitHub URL format"
   cart
     title "Your cart"
     items
@@ -54,9 +70,36 @@ en
     other "They are a developer"
 ```
 
-Nested plural and context groups flatten to the runtime suffix keys
-`cart.items_one`, `cart.items_other`, and `role_female`. A single file may also
-contain several top-level locale blocks, for example `en` followed by `ru`.
+Deeply nested blocks flatten to canonical dot keys such as
+`telegram.help.solve.alias.detail` and
+`prompt.system.general.guidelines.body`. Nested plural and context groups still
+flatten to runtime suffix keys such as `cart.items_one`, `cart.items_other`,
+and `role_female`. A single file may also contain several top-level locale
+blocks, for example `en` followed by `ru`.
+
+Use a `label` child when a translated group also needs its own runtime key:
+`error.label` and `error` both resolve to `"Error"`, and an explicit `error`
+translation wins over the generated alias.
+
+For migrations from flatter catalogues, enable compatibility aliases when
+loading or creating the runtime:
+
+```js
+const catalogues = await loadLocalesFromDirectory('./locales', {
+  compatibilityAliases: ['collapseTail', 'parentLabel'],
+});
+const i18n = createI18n({
+  locales: catalogues,
+  defaultLocale: 'en',
+});
+```
+
+`collapseTail` exposes underscore-tail aliases for deeper keys, so
+`telegram.help.solve.alias.detail` also resolves through
+`telegram.help_solve_alias_detail`, `telegram.help.solve_alias_detail`, and
+`telegram.help.solve.alias_detail`. `parentLabel` maps `error.label` to the
+legacy parent key `error`. Generated aliases never overwrite explicit
+translations.
 
 ## CLI
 
@@ -90,7 +133,9 @@ Run `npx lino-i18n --help` for every option.
 - `{{var}}` and `{var}` placeholder syntax for compatibility with i18next
   and `react-intl`.
 - Context (gender) suffixes: `role_male`, `role_female`, `role_other`.
+- Migration aliases for deeper nested keys and parent labels.
 - Namespace prefixes via `:` (`navigation:home`) and `.` (`cart.title`).
+- Group label aliases via `label` children.
 - Configurable fallback chain.
 - Bundled multi-locale `.lino` files and per-language directories.
 - Optional missing-key handler.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lino-i18n",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Universal i18n library that stores translations in Links Notation (.lino) instead of JSON.",
   "type": "module",
   "main": "./src/index.js",

package/src/compatibility.js

@@ -0,0 +1,85 @@
+// Compatibility helpers for catalogue migrations. These helpers work on the
+// flat key tables produced by the loader and only add aliases for keys that do
+// not already exist.
+
+const ALIAS_NAMES = new Map([
+  ['collapseTail', 'collapseTail'],
+  ['collapse-tail', 'collapseTail'],
+  ['parentLabel', 'parentLabel'],
+  ['parent-label', 'parentLabel'],
+]);
+
+function toAliasList(options = {}) {
+  if (Array.isArray(options) || typeof options === 'string') {
+    return Array.isArray(options) ? options : [options];
+  }
+  const requested = options.compatibilityAliases ?? options.mode ?? [];
+  return Array.isArray(requested) ? requested : [requested];
+}
+
+export function normalizeCompatibilityAliases(options = {}) {
+  const normalized = [];
+  for (const alias of toAliasList(options)) {
+    if (!alias) {
+      continue;
+    }
+    const name = ALIAS_NAMES.get(String(alias));
+    if (!name) {
+      throw new TypeError(`unknown compatibility alias mode: ${alias}`);
+    }
+    if (!normalized.includes(name)) {
+      normalized.push(name);
+    }
+  }
+  return normalized;
+}
+
+function collapseTailAliases(key) {
+  const parts = key.split('.');
+  if (parts.length < 3) {
+    return [];
+  }
+  const aliases = [];
+  for (let index = 1; index < parts.length - 1; index += 1) {
+    aliases.push(
+      `${parts.slice(0, index).join('.')}.${parts.slice(index).join('_')}`
+    );
+  }
+  return aliases;
+}
+
+function parentLabelAlias(key) {
+  if (!key.endsWith('.label')) {
+    return null;
+  }
+  const parent = key.slice(0, -'.label'.length);
+  return parent || null;
+}
+
+export function expandCompatibilityAliases(translations, options = {}) {
+  const aliases = normalizeCompatibilityAliases(options);
+  const expanded = { ...(translations || {}) };
+  if (aliases.length === 0) {
+    return expanded;
+  }
+
+  const hasOwn = Object.prototype.hasOwnProperty;
+  for (const [key, value] of Object.entries(translations || {})) {
+    if (aliases.includes('collapseTail')) {
+      for (const alias of collapseTailAliases(key)) {
+        if (!hasOwn.call(expanded, alias)) {
+          expanded[alias] = value;
+        }
+      }
+    }
+
+    if (aliases.includes('parentLabel')) {
+      const alias = parentLabelAlias(key);
+      if (alias && !hasOwn.call(expanded, alias)) {
+        expanded[alias] = value;
+      }
+    }
+  }
+
+  return expanded;
+}

package/src/format.js

@@ -3,6 +3,7 @@
 // resolution algorithm shared between the runtime and the CLI.
 
 const INTERPOLATION_PATTERN = /\{\{?\s*([\w.$:-]+)\s*\}?\}/g;
+const LABEL_ALIAS_KEY = 'label';
 
 const PLURAL_SUFFIXES = ['zero', 'one', 'two', 'few', 'many', 'other'];
 
@@ -100,6 +101,10 @@ export function resolveKey(table, key, { count, context, locale } = {}) {
     if (direct !== undefined) {
       return direct;
     }
+    const labelAlias = lookup(table, `${target}.${LABEL_ALIAS_KEY}`);
+    if (labelAlias !== undefined) {
+      return labelAlias;
+    }
   }
 
   if (context) {
@@ -112,4 +117,8 @@ export function resolveKey(table, key, { count, context, locale } = {}) {
   return undefined;
 }
 
-export const _internals = { PLURAL_SUFFIXES, INTERPOLATION_PATTERN };
+export const _internals = {
+  PLURAL_SUFFIXES,
+  INTERPOLATION_PATTERN,
+  LABEL_ALIAS_KEY,
+};

package/src/i18n.js

@@ -8,6 +8,10 @@ import {
   loadLocalesFromFile,
   loadLocalesFromDirectory,
 } from './loaders.js';
+import {
+  expandCompatibilityAliases,
+  normalizeCompatibilityAliases,
+} from './compatibility.js';
 import { interpolate, resolveKey } from './format.js';
 
 function normalizeFallbacks(fallback) {
@@ -27,11 +31,18 @@ export function createI18n(options = {}) {
     fallback = ['en'],
     onMissingKey,
     interpolation = { prefix: '{{', suffix: '}}' },
+    compatibilityAliases: requestedCompatibilityAliases = [],
   } = options;
+  const compatibilityAliases = normalizeCompatibilityAliases(
+    requestedCompatibilityAliases
+  );
 
   const catalogues = new Map();
   for (const [locale, translations] of Object.entries(locales)) {
-    catalogues.set(locale, { ...translations });
+    catalogues.set(
+      locale,
+      expandCompatibilityAliases(translations, { compatibilityAliases })
+    );
   }
 
   let currentLocale = defaultLocale;
@@ -58,7 +69,7 @@ export function createI18n(options = {}) {
 
   function has(key, locale = currentLocale) {
     const table = catalogues.get(locale);
-    return Boolean(table && Object.prototype.hasOwnProperty.call(table, key));
+    return resolveKey(table, key, { locale }) !== undefined;
   }
 
   function _lookup(key, opts) {
@@ -117,7 +128,13 @@ export function createI18n(options = {}) {
       throw new TypeError('addLocale requires a string locale name');
     }
     const current = catalogues.get(locale) || {};
-    catalogues.set(locale, { ...current, ...translations });
+    catalogues.set(
+      locale,
+      expandCompatibilityAliases(
+        { ...current, ...translations },
+        { compatibilityAliases }
+      )
+    );
   }
 
   async function loadLocale(locale, text) {

package/src/index.d.ts

@@ -1,5 +1,18 @@
 // Type declarations for the `lino-i18n` package.
 
+export type CompatibilityAlias =
+  | 'collapseTail'
+  | 'collapse-tail'
+  | 'parentLabel'
+  | 'parent-label';
+
+export interface CompatibilityAliasOptions {
+  /** Alias modes used to expose migration keys without overwriting explicit keys. */
+  compatibilityAliases?: CompatibilityAlias | CompatibilityAlias[];
+  /** Alias mode shortcut for helper-style calls. */
+  mode?: CompatibilityAlias | CompatibilityAlias[];
+}
+
 export interface I18nOptions {
   /** Translation catalogues keyed by locale code. */
   locales?: Record<string, Record<string, string>>;
@@ -15,6 +28,8 @@ export interface I18nOptions {
   }) => string | void;
   /** Interpolation tokens; currently informational only. */
   interpolation?: { prefix?: string; suffix?: string };
+  /** Compatibility aliases generated from canonical keys during migration. */
+  compatibilityAliases?: CompatibilityAlias | CompatibilityAlias[];
 }
 
 export interface TOptions {
@@ -51,15 +66,33 @@ export interface I18nInstance {
 
 export declare function createI18n(options?: I18nOptions): I18nInstance;
 
+export declare function expandCompatibilityAliases(
+  translations: Record<string, string>,
+  options?: CompatibilityAliasOptions
+): Record<string, string>;
+
 export declare function parseLinoCatalog(text: string): {
   locale: string | null;
   translations: Record<string, string>;
 };
 
+export declare function parseLinoCatalog(
+  text: string,
+  options: CompatibilityAliasOptions
+): {
+  locale: string | null;
+  translations: Record<string, string>;
+};
+
 export declare function parseLinoCatalogs(
   text: string
 ): Array<{ locale: string | null; translations: Record<string, string> }>;
 
+export declare function parseLinoCatalogs(
+  text: string,
+  options: CompatibilityAliasOptions
+): Array<{ locale: string | null; translations: Record<string, string> }>;
+
 export declare function formatLinoCatalog(
   locale: string,
   translations: Record<string, string>,
@@ -75,19 +108,23 @@ export declare function formatLinoCatalogs(
 
 export declare function loadLocaleFromString(
   locale: string,
-  text: string
+  text: string,
+  options?: CompatibilityAliasOptions
 ): Promise<{ locale: string; translations: Record<string, string> }>;
 
 export declare function loadLocaleFromFile(
-  filePath: string
+  filePath: string,
+  options?: CompatibilityAliasOptions
 ): Promise<{ locale: string; translations: Record<string, string> }>;
 
 export declare function loadLocalesFromFile(
-  filePath: string
+  filePath: string,
+  options?: CompatibilityAliasOptions
 ): Promise<Array<{ locale: string; translations: Record<string, string> }>>;
 
 export declare function loadLocalesFromDirectory(
-  directory: string
+  directory: string,
+  options?: CompatibilityAliasOptions
 ): Promise<Record<string, Record<string, string>>>;
 
 export declare function interpolate(

package/src/index.js

@@ -8,6 +8,7 @@
 // framework.
 
 export { createI18n } from './i18n.js';
+export { expandCompatibilityAliases } from './compatibility.js';
 export {
   parseLinoCatalog,
   parseLinoCatalogs,

package/src/loaders.js

@@ -7,6 +7,8 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
+import { expandCompatibilityAliases } from './compatibility.js';
+
 const SELECTOR_SUFFIXES = new Set([
   'zero',
   'one',
@@ -19,6 +21,8 @@ const SELECTOR_SUFFIXES = new Set([
   'neutral',
 ]);
 
+const LABEL_ALIAS_KEY = 'label';
+
 function unescapeValue(value, quote = '"') {
   let result = '';
   for (let index = 0; index < value.length; index += 1) {
@@ -275,7 +279,9 @@ function isPlainObject(value) {
 }
 
 function isSelectorGroup(value) {
-  const entries = Object.entries(value);
+  const entries = Object.entries(value).filter(
+    ([key]) => key !== LABEL_ALIAS_KEY
+  );
   return (
     entries.length > 0 &&
     entries.every(
@@ -284,6 +290,18 @@ function isSelectorGroup(value) {
   );
 }
 
+function labelAliasValue(value) {
+  return typeof value[LABEL_ALIAS_KEY] === 'string'
+    ? value[LABEL_ALIAS_KEY]
+    : undefined;
+}
+
+function addLabelAlias(out, base, value) {
+  if (!Object.prototype.hasOwnProperty.call(out, base)) {
+    out[base] = value;
+  }
+}
+
 function flattenTree(tree, pathParts = [], out = {}) {
   for (const [key, value] of Object.entries(tree)) {
     if (typeof value === 'string') {
@@ -295,14 +313,25 @@ function flattenTree(tree, pathParts = [], out = {}) {
     }
 
     const nextPath = [...pathParts, key];
+    const base = nextPath.join('.');
+    const labelValue = labelAliasValue(value);
     if (isSelectorGroup(value)) {
-      const base = nextPath.join('.');
+      if (labelValue !== undefined) {
+        out[`${base}.${LABEL_ALIAS_KEY}`] = labelValue;
+        addLabelAlias(out, base, labelValue);
+      }
       for (const [suffix, child] of Object.entries(value)) {
+        if (suffix === LABEL_ALIAS_KEY) {
+          continue;
+        }
         out[`${base}_${suffix}`] = child;
       }
       continue;
     }
     flattenTree(value, nextPath, out);
+    if (labelValue !== undefined) {
+      addLabelAlias(out, base, labelValue);
+    }
   }
   return out;
 }
@@ -322,12 +351,23 @@ function splitSelectorSuffix(key) {
 function setNestedValue(tree, parts, value) {
   let node = tree;
   for (const part of parts.slice(0, -1)) {
-    if (!isPlainObject(node[part])) {
+    const current = node[part];
+    if (!isPlainObject(current)) {
       node[part] = {};
+      if (typeof current === 'string') {
+        node[part][LABEL_ALIAS_KEY] = current;
+      }
     }
     node = node[part];
   }
-  node[parts[parts.length - 1]] = value;
+  const leaf = parts[parts.length - 1];
+  if (isPlainObject(node[leaf])) {
+    if (!Object.prototype.hasOwnProperty.call(node[leaf], LABEL_ALIAS_KEY)) {
+      node[leaf][LABEL_ALIAS_KEY] = value;
+    }
+    return;
+  }
+  node[leaf] = value;
 }
 
 function translationsToTree(translations) {
@@ -360,7 +400,12 @@ function formatValue(value, indent) {
 
 function formatTreeLines(tree, indent = '  ') {
   const lines = [];
-  for (const [key, value] of Object.entries(tree)) {
+  const entries = Object.entries(tree);
+  const labelEntry = entries.find(([key]) => key === LABEL_ALIAS_KEY);
+  const orderedEntries = labelEntry
+    ? [labelEntry, ...entries.filter(([key]) => key !== LABEL_ALIAS_KEY)]
+    : entries;
+  for (const [key, value] of orderedEntries) {
     if (typeof value === 'string') {
       lines.push(`${indent}${key} ${formatValue(value, indent)}`);
       continue;
@@ -386,16 +431,16 @@ function formatFlatCatalog(locale, translations) {
 // Parse the contents of one `.lino` catalogue. Returns the first
 // `{ locale, translations }` pair when the file contains multiple locale
 // roots. Use `parseLinoCatalogs` to keep every root.
-export function parseLinoCatalog(text) {
-  const catalogues = parseLinoCatalogs(text);
+export function parseLinoCatalog(text, options = {}) {
+  const catalogues = parseLinoCatalogs(text, options);
   return catalogues[0] || { locale: null, translations: {} };
 }
 
 // Parse every top-level locale block in a `.lino` string.
-export function parseLinoCatalogs(text) {
+export function parseLinoCatalogs(text, options = {}) {
   return parseLocaleTrees(text).map(({ locale, tree }) => ({
     locale: locale || null,
-    translations: flattenTree(tree),
+    translations: expandCompatibilityAliases(flattenTree(tree), options),
   }));
 }
 
@@ -427,8 +472,8 @@ export function formatLinoCatalogs(catalogues, options = {}) {
     .join('\n\n');
 }
 
-export async function loadLocaleFromString(locale, text) {
-  const parsedCatalogues = parseLinoCatalogs(text);
+export async function loadLocaleFromString(locale, text, options = {}) {
+  const parsedCatalogues = parseLinoCatalogs(text, options);
   const parsed = parsedCatalogues.find(
     (catalogue) => catalogue.locale === locale
   ) ||
@@ -439,17 +484,17 @@ export async function loadLocaleFromString(locale, text) {
   };
 }
 
-export async function loadLocaleFromFile(filePath) {
+export async function loadLocaleFromFile(filePath, options = {}) {
   const text = await fs.readFile(filePath, 'utf8');
-  const parsed = parseLinoCatalog(text);
+  const parsed = parseLinoCatalog(text, options);
   const locale =
     parsed.locale || path.basename(filePath, path.extname(filePath));
   return { locale, translations: parsed.translations };
 }
 
-export async function loadLocalesFromFile(filePath) {
+export async function loadLocalesFromFile(filePath, options = {}) {
   const text = await fs.readFile(filePath, 'utf8');
-  const parsed = parseLinoCatalogs(text);
+  const parsed = parseLinoCatalogs(text, options);
   if (parsed.length > 0) {
     return parsed;
   }
@@ -461,7 +506,7 @@ export async function loadLocalesFromFile(filePath) {
   ];
 }
 
-export async function loadLocalesFromDirectory(directory) {
+export async function loadLocalesFromDirectory(directory, options = {}) {
   const entries = (await fs.readdir(directory, { withFileTypes: true })).sort(
     (left, right) => left.name.localeCompare(right.name)
   );
@@ -486,5 +531,8 @@ export async function loadLocalesFromDirectory(directory) {
       };
     }
   }
+  for (const [locale, translations] of Object.entries(catalogues)) {
+    catalogues[locale] = expandCompatibilityAliases(translations, options);
+  }
   return catalogues;
 }