locon 1.4.4 → 1.5.0

package/skills/locon-sync/scripts/write_locale.py

@@ -0,0 +1,229 @@
+#!/usr/bin/env python3
+"""Validate and write one flat locon locale JSON file.
+
+Use as a CLI from any project directory:
+
+    python3 write_locale.py --locale fr --input /tmp/fr.json \
+      --assets src/i18n/assets --source de
+
+Or import `write()` and pass the same values as a dictionary. The source file
+defines key order and grouping; target-only CLDR plural categories stay beside
+their family. Invalid parity, placeholders, duplicate JSON keys, and unsafe
+locale names fail before the destination is touched.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import re
+import tempfile
+from typing import Iterable
+
+DEFAULT_ASSETS = pathlib.Path(os.environ.get('LOCON_ASSETS', 'src/i18n/assets'))
+DEFAULT_SOURCE_LOCALE = os.environ.get('LOCON_SOURCE', 'en')
+
+PLURAL = re.compile(r'_(zero|one|two|few|many|other)$')
+PLURAL_CATEGORIES = ('zero', 'one', 'two', 'few', 'many', 'other')
+LOCALE_NAME = re.compile(r'^[A-Za-z]{2,8}(?:[-_][A-Za-z0-9]{1,8})*$')
+
+
+class DuplicateKeyError(ValueError):
+    """Raised when JSON would silently overwrite a translation key."""
+
+
+def _unique_object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise DuplicateKeyError(f'duplicate key: {key}')
+        result[key] = value
+    return result
+
+
+def _read_flat_asset(path: pathlib.Path) -> dict[str, str]:
+    try:
+        value = json.loads(
+            path.read_text(encoding='utf-8'),
+            object_pairs_hook=_unique_object,
+        )
+    except (OSError, json.JSONDecodeError, DuplicateKeyError) as error:
+        raise SystemExit(f'{path}: {error}') from error
+
+    if not isinstance(value, dict) or any(
+        not isinstance(key, str) or not isinstance(item, str)
+        for key, item in value.items()
+    ):
+        raise SystemExit(f'{path}: expected a flat JSON object with string values')
+    return value
+
+
+def _source_boundaries(path: pathlib.Path) -> set[str]:
+    boundaries = set()
+    previous = None
+    for line in path.read_text(encoding='utf-8').splitlines():
+        match = re.match(r'\s*"([^"]+)":', line)
+        if match:
+            previous = match.group(1)
+        elif not line.strip() and previous:
+            boundaries.add(previous)
+    return boundaries
+
+
+def _validate_locale(locale: str) -> None:
+    if not LOCALE_NAME.fullmatch(locale):
+        raise SystemExit(f'invalid locale name: {locale!r}')
+
+
+def write(
+    locale: str,
+    values: dict[str, str],
+    *,
+    assets: pathlib.Path | str = DEFAULT_ASSETS,
+    source_locale: str = DEFAULT_SOURCE_LOCALE,
+    allow_implicit_count: Iterable[str] = (),
+) -> None:
+    """Validate `values` and atomically write `<assets>/<locale>.json`."""
+    _validate_locale(locale)
+    _validate_locale(source_locale)
+
+    asset_dir = pathlib.Path(assets)
+    source_path = asset_dir / f'{source_locale}.json'
+    if not source_path.exists():
+        raise SystemExit(f'source locale not found: {source_path}')
+
+    source = _read_flat_asset(source_path)
+    if not isinstance(values, dict) or any(
+        not isinstance(key, str) or not isinstance(value, str)
+        for key, value in values.items()
+    ):
+        raise SystemExit(f'{locale}: expected a dictionary with string values')
+
+    families = {PLURAL.sub('', key) for key in source if PLURAL.search(key)}
+    missing_other = [family for family in sorted(families) if f'{family}_other' not in source]
+    if missing_other:
+        raise SystemExit(
+            f'{source_locale}: plural families must define an _other catch-all: '
+            + ', '.join(missing_other)
+        )
+
+    missing = [key for key in source if key not in values]
+    unknown = [
+        key for key in values
+        if key not in source and not (PLURAL.search(key) and PLURAL.sub('', key) in families)
+    ]
+    if missing:
+        raise SystemExit(f'{locale}: missing {len(missing)} keys: {missing}')
+    if unknown:
+        raise SystemExit(f'{locale}: unknown keys: {unknown}')
+
+    allowances = set(allow_implicit_count)
+    used_allowances = set()
+
+    for key, value in values.items():
+        source_key = PLURAL.sub('_other', key) if PLURAL.search(key) else key
+        if source_key not in source:
+            continue
+        want = set(re.findall(r'\{(\w+)\}', source[source_key]))
+        got = set(re.findall(r'\{(\w+)\}', value))
+        introduced = got - want
+        dropped = want - got
+
+        if introduced:
+            raise SystemExit(f'{locale}.{key}: unknown placeholders {sorted(introduced)}')
+        if dropped == {'count'} and key in allowances:
+            used_allowances.add(key)
+        elif dropped:
+            suffix = (
+                f'; pass allow_implicit_count={{\'{key}\'}} if the wording states the exact number'
+                if 'count' in dropped else ''
+            )
+            raise SystemExit(f'{locale}.{key}: missing placeholders {sorted(dropped)}{suffix}')
+
+    unused_allowances = allowances - used_allowances
+    if unused_allowances:
+        raise SystemExit(f'{locale}: unused allow_implicit_count keys: {sorted(unused_allowances)}')
+
+    ordered = []
+    for key in source:
+        if key not in ordered:
+            ordered.append(key)
+        if PLURAL.search(key):
+            base = PLURAL.sub('', key)
+            for category in PLURAL_CATEGORIES:
+                sibling = f'{base}_{category}'
+                if sibling in values and sibling not in ordered:
+                    ordered.append(sibling)
+
+    boundaries = _source_boundaries(source_path)
+    expanded_boundaries = set()
+    for boundary in boundaries:
+        if PLURAL.search(boundary):
+            family = PLURAL.sub('', boundary)
+            siblings = [key for key in ordered if PLURAL.search(key) and PLURAL.sub('', key) == family]
+            if siblings:
+                expanded_boundaries.add(siblings[-1])
+        else:
+            expanded_boundaries.add(boundary)
+
+    lines = ['{']
+    for index, key in enumerate(ordered):
+        comma = '' if index == len(ordered) - 1 else ','
+        lines.append(f'  {json.dumps(key)}: {json.dumps(values[key], ensure_ascii=False)}{comma}')
+        if key in expanded_boundaries and index != len(ordered) - 1:
+            lines.append('')
+    lines.append('}')
+
+    asset_dir.mkdir(parents=True, exist_ok=True)
+    destination = asset_dir / f'{locale}.json'
+    destination_mode = destination.stat().st_mode & 0o777 if destination.exists() else 0o644
+    temporary_path = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode='w',
+            encoding='utf-8',
+            dir=asset_dir,
+            prefix=f'.{locale}.',
+            suffix='.tmp',
+            delete=False,
+        ) as temporary:
+            temporary.write('\n'.join(lines) + '\n')
+            temporary_path = pathlib.Path(temporary.name)
+        temporary_path.chmod(destination_mode)
+        temporary_path.replace(destination)
+    finally:
+        if temporary_path and temporary_path.exists():
+            temporary_path.unlink()
+
+    print(f'{locale}.json: {len(values)} keys')
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--locale', required=True, help='target BCP-47 locale and output filename')
+    parser.add_argument('--input', required=True, type=pathlib.Path, help='flat JSON file with translated values')
+    parser.add_argument('--assets', type=pathlib.Path, default=DEFAULT_ASSETS, help='asset directory')
+    parser.add_argument('--source', default=DEFAULT_SOURCE_LOCALE, help='source locale (default: en)')
+    parser.add_argument(
+        '--allow-implicit-count',
+        default='',
+        help='comma-separated target keys intentionally omitting {count}',
+    )
+    args = parser.parse_args()
+    _validate_locale(args.locale)
+    _validate_locale(args.source)
+    values = _read_flat_asset(args.input)
+    allowances = [item.strip() for item in args.allow_implicit_count.split(',') if item.strip()]
+    write(
+        args.locale,
+        values,
+        assets=args.assets,
+        source_locale=args.source,
+        allow_implicit_count=allowances,
+    )
+
+
+if __name__ == '__main__':
+    main()

package/dist/components/LText.d.mts

@@ -1,10 +0,0 @@
-import { ReactElement, ComponentProps } from 'react';
-import { Text } from 'react-native';
-
-interface Props extends ComponentProps<typeof Text> {
-    children: string;
-    assetKey?: string;
-}
-declare function LText({ children, assetKey, ...props }: Props): ReactElement;
-
-export { LText as default };

package/dist/components/LText.d.ts

@@ -1,10 +0,0 @@
-import { ReactElement, ComponentProps } from 'react';
-import { Text } from 'react-native';
-
-interface Props extends ComponentProps<typeof Text> {
-    children: string;
-    assetKey?: string;
-}
-declare function LText({ children, assetKey, ...props }: Props): ReactElement;
-
-export { LText as default };

package/dist/components/LText.js

@@ -1,41 +0,0 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var LText_exports = {};
-__export(LText_exports, {
-  default: () => LText_default
-});
-module.exports = __toCommonJS(LText_exports);
-var import_jsx_runtime = require("react/jsx-runtime");
-var import_react_native = require("react-native");
-var import_useLocon = __toESM(require("../hooks/useLocon"));
-function LText({ children, assetKey, ...props }) {
-  const { l } = (0, import_useLocon.default)();
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_native.Text, { ...props, children: l(assetKey || children) });
-}
-var LText_default = LText;

package/dist/components/LText.mjs

@@ -1,11 +0,0 @@
-import { jsx } from "react/jsx-runtime";
-import { Text } from "react-native";
-import useLocon from "../hooks/useLocon";
-function LText({ children, assetKey, ...props }) {
-  const { l } = useLocon();
-  return /* @__PURE__ */ jsx(Text, { ...props, children: l(assetKey || children) });
-}
-var LText_default = LText;
-export {
-  LText_default as default
-};

package/dist/hooks/useLocon.d.mts

@@ -1,6 +0,0 @@
-import LoconContext from '../types/LoconContext.mjs';
-import '../types/Assets.mjs';
-
-declare function useLocon(): LoconContext;
-
-export { useLocon as default };

package/dist/hooks/useLocon.d.ts

@@ -1,6 +0,0 @@
-import LoconContext from '../types/LoconContext.js';
-import '../types/Assets.js';
-
-declare function useLocon(): LoconContext;
-
-export { useLocon as default };

package/dist/hooks/useLocon.js

@@ -1,30 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var useLocon_exports = {};
-__export(useLocon_exports, {
-  default: () => useLocon_default
-});
-module.exports = __toCommonJS(useLocon_exports);
-var import_react = require("react");
-var import__ = require("../index");
-function useLocon() {
-  const locon = (0, import_react.useContext)(import__.LoconContext);
-  return locon;
-}
-var useLocon_default = useLocon;

package/dist/hooks/useLocon.mjs

@@ -1,10 +0,0 @@
-import { useContext } from "react";
-import { LoconContext } from "../index";
-function useLocon() {
-  const locon = useContext(LoconContext);
-  return locon;
-}
-var useLocon_default = useLocon;
-export {
-  useLocon_default as default
-};

package/dist/index.d.mts

@@ -1,19 +0,0 @@
-import * as react from 'react';
-import { ReactElement, PropsWithChildren } from 'react';
-import LoconContext$1 from './types/LoconContext.mjs';
-export { default as LText } from './components/LText.mjs';
-export { default as useLocon } from './hooks/useLocon.mjs';
-import './types/Assets.mjs';
-import 'react-native';
-
-declare const LoconContext: react.Context<LoconContext$1>;
-interface Props extends PropsWithChildren {
-    assets?: Record<string, Record<string, string>>;
-    currentLocale?: string;
-    defaultLocale?: string;
-    projectLocale?: string;
-    autodetect?: boolean;
-}
-declare function Locon({ children, assets, currentLocale: currentLocaleProps, defaultLocale, projectLocale, autodetect, }: Props): ReactElement;
-
-export { LoconContext, Locon as default };

package/dist/index.mjs

@@ -1,104 +0,0 @@
-import { jsx } from "react/jsx-runtime";
-import { createContext, useCallback, useEffect, useMemo, useState } from "react";
-import getSystemLanguage from "./utils/getSystemLanguage";
-const LoconContext = createContext({
-  assets: {},
-  currentLocale: "en",
-  defaultLocale: "en",
-  autodetect: true,
-  setLocale: () => {
-  },
-  // Default implementation
-  l: (assetKey) => assetKey
-  // Default implementation
-});
-function Locon({
-  children,
-  assets = {},
-  currentLocale: currentLocaleProps,
-  defaultLocale = "en",
-  projectLocale = "en",
-  autodetect = true
-}) {
-  const resolvedProjectLocale = projectLocale || defaultLocale;
-  const [currentLocale, setCurrentLocale] = useState(() => {
-    if (currentLocaleProps) {
-      return currentLocaleProps;
-    }
-    if (autodetect) {
-      const systemLocale = getSystemLanguage(Object.keys(assets));
-      if (systemLocale && assets[systemLocale]) {
-        return systemLocale;
-      }
-    }
-    return defaultLocale;
-  });
-  const getAssets = useCallback(() => {
-    const currentAssets = assets[currentLocale] ?? assets[defaultLocale];
-    return currentAssets ?? {};
-  }, [assets, currentLocale, defaultLocale]);
-  const getAsset = useCallback(
-    (assetKey) => {
-      const assetsObj = getAssets();
-      return assetsObj[assetKey] ?? "";
-    },
-    [getAssets]
-  );
-  const setCurrentLocaleHandler = useCallback(
-    (locale) => {
-      if (assets[locale]) {
-        setCurrentLocale(locale);
-      } else {
-        console.warn(`[locon] Locale "${locale}" not found in assets.`);
-      }
-    },
-    [assets]
-  );
-  const getAssetByValue = useCallback(
-    (assetValue, locale = resolvedProjectLocale) => {
-      const currentAssets = assets[locale];
-      if (!currentAssets) {
-        return void 0;
-      }
-      const assetKey = Object.keys(currentAssets).find((key) => currentAssets[key] === assetValue);
-      return assetKey ? getAsset(assetKey) : void 0;
-    },
-    [assets, getAsset, resolvedProjectLocale]
-  );
-  const l = useCallback(
-    (assetKey) => {
-      if (!assetKey) {
-        return "";
-      }
-      const asset = getAsset(assetKey) || getAssetByValue(assetKey) || getAssetByValue(assetKey, defaultLocale);
-      return asset ?? assetKey;
-    },
-    [getAsset, getAssetByValue, defaultLocale]
-  );
-  useEffect(() => {
-    if (currentLocaleProps) {
-      setCurrentLocale((locale) => locale === currentLocaleProps ? locale : currentLocaleProps);
-    }
-  }, [currentLocaleProps]);
-  const value = useMemo(
-    () => ({
-      assets,
-      currentLocale,
-      defaultLocale,
-      autodetect,
-      l,
-      setLocale: setCurrentLocaleHandler
-    }),
-    [assets, currentLocale, defaultLocale, autodetect, l, setCurrentLocaleHandler]
-  );
-  return /* @__PURE__ */ jsx(LoconContext, { value, children });
-}
-var locon_default = Locon;
-import { default as default2 } from "./components/LText";
-import { default as default3 } from "./hooks/useLocon";
-export {
-  default2 as LText,
-  LoconContext,
-  locon_default as default,
-  default3 as useLocon
-};

package/dist/types/Assets.d.mts

@@ -1,3 +0,0 @@
-type Assets = Record<string, Record<string, string>>;
-
-export type { Assets as default };

package/dist/types/Assets.d.ts

@@ -1,3 +0,0 @@
-type Assets = Record<string, Record<string, string>>;
-
-export type { Assets as default };

package/dist/types/Assets.js

@@ -1,16 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var Assets_exports = {};
-module.exports = __toCommonJS(Assets_exports);

package/dist/types/LoconContext.d.mts

@@ -1,12 +0,0 @@
-import Assets from './Assets.mjs';
-
-interface LoconContext {
-    l: (assetKey: string) => string;
-    assets: Assets;
-    currentLocale: string;
-    defaultLocale: string;
-    autodetect: boolean;
-    setLocale: (locale: string) => void;
-}
-
-export type { LoconContext as default };

package/dist/types/LoconContext.d.ts

@@ -1,12 +0,0 @@
-import Assets from './Assets.js';
-
-interface LoconContext {
-    l: (assetKey: string) => string;
-    assets: Assets;
-    currentLocale: string;
-    defaultLocale: string;
-    autodetect: boolean;
-    setLocale: (locale: string) => void;
-}
-
-export type { LoconContext as default };

package/dist/types/LoconContext.js

@@ -1,16 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var LoconContext_exports = {};
-module.exports = __toCommonJS(LoconContext_exports);

package/dist/utils/getSystemLanguage.d.mts

@@ -1,7 +0,0 @@
-/**
- * Detects the system language and returns the best matching available locale.
- * Uses react-native-localize if available, otherwise falls back to native APIs.
- */
-declare function getSystemLanguage(availableLocales?: string[]): string | null;
-
-export { getSystemLanguage as default };

package/dist/utils/getSystemLanguage.d.ts

@@ -1,7 +0,0 @@
-/**
- * Detects the system language and returns the best matching available locale.
- * Uses react-native-localize if available, otherwise falls back to native APIs.
- */
-declare function getSystemLanguage(availableLocales?: string[]): string | null;
-
-export { getSystemLanguage as default };