@to-kn/koa-locales 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+This software is licensed under the MIT License.
+
+Copyright (c) 2015 - 2017 koajs and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# koa-locales
+
+A modern i18n solution for Koa: [@to-kn/koa-locales](https://github.com/to-kn/koa-locales)
+
+**Now TypeScript-first, ESM, and Node.js 18+!**
+- Uses ESM (`import`/`export`), outputs to `dist/esm/`, and is CI-tested on GitHub Actions.
+- Use the built output (`dist/esm/index.js`) as the main entry point for consumers, but tests and development use the source (`src/`).
+- Modern test suite with [Vitest](https://vitest.dev/).
+
+[![NPM version][npm-image]][npm-url]
+
+koa locales, i18n solution for koa:
+
+1. All locales resources location on `options.dirs`.
+2. resources file supports: `*.js`, `*.json`, `*.yml`, `*.yaml` and `*.properties`, see [examples](test/locales/).
+3. One api: `__(key[, value, ...])`.
+4. Auto detect request locale from `query`, `cookie` and `header: Accept-Language`.
+
+## Requirements
+
+- Node.js >= 18
+- ESM ("type": "module" in package.json)
+- TypeScript (for development)
+
+## Installation
+
+```sh
+npm install @to-kn/koa-locales
+```
+
+## Quick start (ESM/TypeScript)
+
+```js
+import locales from '@to-kn/koa-locales';
+import Koa from 'koa';
+
+const app = new Koa();
+const options = {
+  dirs: [__dirname + '/locales', __dirname + '/foo/locales'],
+};
+locales(app, options);
+```
+
+## Development & Testing
+
+- Run tests with [Vitest](https://vitest.dev/):
+  ```sh
+  npm run test
+  ```
+- Lint and format with [Biome](https://biomejs.dev/):
+  ```sh
+  npm run lint
+  ```
+- Build TypeScript to ESM:
+  ```sh
+  npm run build
+  ```
+- CI runs on GitHub Actions (see `.github/workflows/`)
+
+## API Reference
+
+### `locales(app, options)`
+
+Patch locales functions to koa app.
+
+- {Application} app: koa app instance.
+- {Object} options: optional params.
+  - {String} functionName: locale function name patch on koa context. Optional, default is `__`.
+  - {String} dirs: locales resources store directories. Optional, default is `['$PWD/locales']`.
+  - {String} defaultLocale: default locale. Optional, default is `en-US`.
+  - {String} queryField: locale field name on query. Optional, default is `locale`.
+  - {String} cookieField: locale field name on cookie. Optional, default is `locale`.
+  - {String} cookieDomain: domain on cookie. Optional, default is `''`.
+  - {Object} localeAlias: locale value map. Optional, default is `{}`.
+  - {Boolean} writeCookie: set cookie if header not sent. Optional, default is `true`.
+  - {String|Number} cookieMaxAge: set locale cookie value max age. Optional, default is `1y`, expired after one year.
+
+```js
+locales({
+  app: app,
+  dirs: [__dirname + '/app/locales'],
+  defaultLocale: 'zh-CN',
+});
+```
+
+#### Aliases
+
+The key `options.localeAlias` allows to not repeat dictionary files, as you can configure to use the same file for *es_ES* for *es*, or *en_UK* for *en*.
+
+```js
+locales({
+  localeAlias: {
+    es: es_ES,
+    en: en_UK,
+  },
+});
+```
+
+### `context.__(key[, value1[, value2, ...]])`
+
+Get current request locale text.
+
+```js
+async function home(ctx) {
+  ctx.body = {
+    message: ctx.__('Hello, %s', 'fengmk2'),
+  };
+}
+```
+
+Examples:
+
+```js
+__('Hello, %s. %s', 'fengmk2', 'koa rock!')
+=>
+'Hello fengmk2. koa rock!'
+
+__('{0} {0} {1} {1} {1}', ['foo', 'bar'])
+=>
+'foo foo bar bar bar'
+
+__('{a} {a} {b} {b} {b}', {a: 'foo', b: 'bar'})
+=>
+'foo foo bar bar bar'
+```
+
+### `context.__getLocale()`
+
+Get locale from query / cookie and header.
+
+### `context.__setLocale()`
+
+Set locale and cookie.
+
+### `context.__getLocaleOrigin()`
+
+Where does locale come from, could be `query`, `cookie`, `header` and `default`.
+
+### `app.__(locale, key[, value1[, value2, ...]])`
+
+Get the given locale text on application level.
+
+```js
+console.log(app.__('zh', 'Hello'));
+// stdout '你好' for Chinese
+```
+
+## Usage on template
+
+```js
+this.state.__ = this.__.bind(this);
+```
+
+[Nunjucks] example:
+
+```html
+{{ __('Hello, %s', user.name) }}
+```
+
+[Pug] example:
+
+```pug
+p= __('Hello, %s', user.name)
+```
+
+[Koa-pug] integration:
+
+You can set the property *locals* on the KoaPug instance, where the default locals are stored.
+
+```js
+app.use(async (ctx, next) => {
+  koaPug.locals.__ = ctx.__.bind(ctx);
+  await next();
+});
+```
+
+## Debugging
+
+If you are interested on knowing what locale was chosen and why you can enable the debug messages from [debug].
+
+There is two level of verbosity:
+
+```sh
+$ DEBUG=koa-locales node .
+```
+With this line it only will show one line per request, with the chosen language and the origin where the locale come from (queryString, header or cookie).
+
+```sh
+$ DEBUG=koa-locales:silly node .
+```
+
+## Locale File Formats
+
+You can provide locale files in the following formats:
+
+- `.json` (recommended for most use cases)
+- `.yml` or `.yaml`
+- `.properties`
+- `.cjs` (CommonJS JavaScript, e.g. `module.exports = { ... }`)
+
+> **Note:** `.js` ESM modules are not supported for synchronous loading. Use `.cjs` for JavaScript locale files if you need sync loading.

package/dist/esm/index.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import util from "node:util";
+import Debug from "debug";
+import { ms } from "humanize-ms";
+import ini from "ini";
+import yaml from "js-yaml";
+const DEFAULT_OPTIONS = {
+    defaultLocale: "en-US",
+    queryField: "locale",
+    cookieField: "locale",
+    localeAlias: {},
+    writeCookie: true,
+    cookieMaxAge: "1y",
+    dir: undefined,
+    dirs: [path.join(process.cwd(), "locales")],
+    functionName: "__",
+};
+function locales(app, options = {}) {
+    options = Object.assign({}, DEFAULT_OPTIONS, options);
+    const defaultLocale = formatLocale(options.defaultLocale || "en-US");
+    const queryField = options.queryField || "locale";
+    const cookieField = options.cookieField || "locale";
+    const cookieDomain = options.cookieDomain;
+    const localeAlias = options.localeAlias || {};
+    const writeCookie = options.writeCookie !== false;
+    const cookieMaxAge = ms(options.cookieMaxAge || "1y");
+    const localeDir = options.dir;
+    const localeDirs = options.dirs || [path.join(process.cwd(), "locales")];
+    const functionName = options.functionName || "__";
+    const resources = {};
+    /**
+     * @Deprecated Use options.dirs instead.
+     */
+    if (localeDir && !localeDirs.includes(localeDir)) {
+        localeDirs.push(localeDir);
+    }
+    appendDebugLog("Starting resource loading");
+    // Loop through all directories, merging resources for the same locale
+    // Later directories override earlier ones
+    for (let i = 0; i < localeDirs.length; i++) {
+        const dir = localeDirs[i];
+        if (!fs.existsSync(dir)) {
+            continue;
+        }
+        const names = fs.readdirSync(dir);
+        for (let j = 0; j < names.length; j++) {
+            const name = names[j];
+            const filepath = path.join(dir, name);
+            // support en_US.js => en-US.js
+            const locale = formatLocale(name.split(".")[0]);
+            let resource = {};
+            if (name.endsWith(".js")) {
+                const require = createRequire(import.meta.url);
+                const mod = require(filepath);
+                resource = flattening((mod.default || mod));
+                appendDebugLog(`Loaded JS resource for locale '${locale}' from: ${filepath}`, resource);
+            }
+            else if (name.endsWith(".json")) {
+                // @ts-ignore
+                resource = flattening(require(filepath));
+                appendDebugLog(`Loaded JSON resource for locale '${locale}' from: ${filepath}`, resource);
+            }
+            else if (name.endsWith(".properties")) {
+                resource = ini.parse(fs.readFileSync(filepath, "utf8"));
+                appendDebugLog(`Loaded PROPERTIES resource for locale '${locale}' from: ${filepath}`, resource);
+            }
+            else if (name.endsWith(".yml") || name.endsWith(".yaml")) {
+                resource = flattening(yaml.load(fs.readFileSync(filepath, "utf8")));
+                appendDebugLog(`Loaded YAML resource for locale '${locale}' from: ${filepath}`, resource);
+            }
+            // Always merge, but let later dirs override earlier ones
+            resources[locale] = { ...resources[locale], ...resource };
+            appendDebugLog(`Merged resource for locale '${locale}'`, resources[locale]);
+        }
+    }
+    appendDebugLog("Finished resource loading");
+    const debug = Debug("koa-locales");
+    const debugSilly = Debug("koa-locales:silly");
+    debug("Init locales with %j, got %j resources", options, Object.keys(resources));
+    if (typeof app[functionName] !==
+        "undefined") {
+        console.warn('[koa-locales] will override exists "%s" function on app', functionName);
+    }
+    function gettext(locale, key, ...args) {
+        if (!key || key === "")
+            return "";
+        const resource = resources[locale] || {};
+        let text = resource[key];
+        if (typeof text !== "string") {
+            text = key;
+        }
+        debugSilly("%s: %j => %j", locale, key, text);
+        if (args.length === 0) {
+            // __(locale, key)
+            return text;
+        }
+        if (args.length === 1) {
+            const value = args[0];
+            if (isObject(value)) {
+                return formatWithObject(text, value);
+            }
+            if (Array.isArray(value)) {
+                return formatWithArray(text, value);
+            }
+            return util.format(text, value);
+        }
+        // __(locale, key, value1, ...)
+        return util.format(text, ...args);
+    }
+    // Attach to app and context using proper Koa extension
+    app[functionName] = gettext;
+    app.context[functionName] =
+        function (key, ...args) {
+            const ctx = this;
+            const locale = ctx.__getLocale ? ctx.__getLocale() : "";
+            return gettext(locale, key, ...args);
+        };
+    app.context.__getLocale =
+        function () {
+            const ctx = this;
+            if (typeof ctx.__locale === "string" && ctx.__locale) {
+                return ctx.__locale;
+            }
+            const cookieLocale = ctx.cookies.get(cookieField, { signed: false });
+            let locale = ctx.query[queryField];
+            let localeOrigin = "query";
+            if (!locale) {
+                locale = cookieLocale;
+                localeOrigin = "cookie";
+            }
+            if (!locale) {
+                let languages = ctx.acceptsLanguages();
+                if (languages) {
+                    if (Array.isArray(languages)) {
+                        if (languages[0] === "*") {
+                            languages = languages.slice(1);
+                        }
+                        if (languages.length > 0) {
+                            for (let i = 0; i < languages.length; i++) {
+                                const lang = formatLocale(String(languages[i]));
+                                if (resources[lang] || localeAlias[lang]) {
+                                    locale = lang;
+                                    localeOrigin = "header";
+                                    break;
+                                }
+                            }
+                        }
+                    }
+                    else if (typeof languages === "string") {
+                        locale = languages;
+                        localeOrigin = "header";
+                    }
+                }
+                if (!locale) {
+                    locale = defaultLocale;
+                    localeOrigin = "default";
+                }
+            }
+            if (locale && typeof locale !== "string") {
+                locale = String(locale);
+            }
+            if (locale && locale in localeAlias) {
+                const originalLocale = locale;
+                locale = localeAlias[locale];
+                debugSilly("Used alias, received %s but using %s", originalLocale, locale);
+            }
+            locale = formatLocale(locale || defaultLocale);
+            if (!resources[locale]) {
+                debugSilly("Locale %s is not supported. Using default (%s)", locale, defaultLocale);
+                locale = defaultLocale;
+            }
+            if (writeCookie && cookieLocale !== locale && !ctx.headerSent) {
+                updateCookie(ctx, locale);
+            }
+            debug("Locale: %s from %s", locale, localeOrigin);
+            debugSilly("Locale: %s from %s", locale, localeOrigin);
+            ctx.__locale = locale;
+            ctx.__localeOrigin = localeOrigin;
+            return String(locale);
+        };
+    app.context.__getLocaleOrigin =
+        function () {
+            const ctx = this;
+            if (typeof ctx.__localeOrigin === "string" && ctx.__localeOrigin)
+                return ctx.__localeOrigin;
+            ctx.__getLocale?.();
+            return String(ctx.__localeOrigin ?? "");
+        };
+    app.context.__setLocale =
+        function (locale) {
+            const ctx = this;
+            ctx.__locale = locale;
+            ctx.__localeOrigin = "set";
+            updateCookie(ctx, locale);
+        };
+    function updateCookie(ctx, locale) {
+        const cookieOptions = {
+            httpOnly: false,
+            maxAge: cookieMaxAge,
+            signed: false,
+            domain: cookieDomain,
+            overwrite: true,
+        };
+        ctx.cookies.set(cookieField, locale, cookieOptions);
+        debugSilly("Saved cookie with locale %s", locale);
+    }
+}
+function isObject(obj) {
+    return Object.prototype.toString.call(obj) === "[object Object]";
+}
+const ARRAY_INDEX_RE = /\{(\d+)\}/g;
+function formatWithArray(text, values) {
+    return text.replace(ARRAY_INDEX_RE, (orignal, matched) => {
+        const index = parseInt(matched);
+        if (index < values.length) {
+            return String(values[index]);
+        }
+        // not match index, return orignal text
+        return orignal;
+    });
+}
+const Object_INDEX_RE = /\{(.+?)\}/g;
+function formatWithObject(text, values) {
+    return text.replace(Object_INDEX_RE, (orignal, matched) => {
+        const value = values[matched];
+        if (value !== undefined && value !== null) {
+            return String(value);
+        }
+        // not match index, return orignal text
+        return orignal;
+    });
+}
+function formatLocale(locale) {
+    if (!locale)
+        return "";
+    return locale.replace(/_/g, "-").toLowerCase();
+}
+function flattening(data) {
+    const result = {};
+    function deepFlat(data, keys) {
+        Object.keys(data).forEach((key) => {
+            const value = data[key];
+            const k = keys ? `${keys}.${key}` : key;
+            if (isObject(value)) {
+                deepFlat(value, k);
+            }
+            else {
+                result[k] = String(value);
+            }
+        });
+    }
+    deepFlat(data, "");
+    return result;
+}
+function appendDebugLog(message, obj) {
+    const logPath = path.resolve(process.cwd(), "resource-debug.log");
+    let line = `[DEBUG] ${message}`;
+    if (obj !== undefined) {
+        try {
+            line += ` ${JSON.stringify(obj)}`;
+        }
+        catch {
+            line += ` ${String(obj)}`;
+        }
+    }
+    fs.appendFileSync(logPath, `${line}
+`);
+}
+export default locales;