@sigil-dev/i18n 0.0.0-stage → 0.9.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +27 -3
  2. package/index.ts +253 -0
  3. package/package.json +35 -4
  4. package/runtime.ts +233 -0
package/README.md CHANGED
@@ -1,3 +1,27 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # @sigil-dev/i18n
2
+
3
+ Languages for a Grimoire app: one JSON file per language, every message typed from the default one, plurals by each language's own rules, and every request served in the visitor's language.
4
+
5
+ ```sh
6
+ sigil add i18n
7
+ ```
8
+
9
+ ```jsonc
10
+ // src/locales/en.json
11
+ { "hello": "Hello, {name}!", "cart": { "items": { "one": "{count} item", "other": "{count} items" } } }
12
+ // src/locales/sr-Latn.json
13
+ { "hello": "Zdravo, {name}!", "cart": { "items": { "one": "{count} stavka", "few": "{count} stavke", "other": "{count} stavki" } } }
14
+ ```
15
+
16
+ ```tsx
17
+ import { m, setLocale } from "$i18n";
18
+
19
+ <a href="/">{m.nav.home}</a> // a message without holes reads like a field
20
+ <h1>{m.hello({ name: user.name })}</h1> // one with holes takes them, typed
21
+ <p>{m.cart.items({ count: cart.length })}</p> // count is required for a plural
22
+ <button onClick={() => setLocale("sr-Latn")}>Srpski</button>
23
+ ```
24
+
25
+ The language is the first path segment when it names one (`/sr-Latn/about`, with `[[lang]]` routes), else the cookie `setLocale` writes, else Accept-Language, else the default. `m` is generated from the default language's file, with each message's text as its doc comment. A message that is not there, or a missing param, is a type error; `translate("key")` is there for keys built at runtime. a translation that is missing falls back to it, and the server says at startup which keys each language lacks.
26
+
27
+ Docs: https://sigil.cane1712.dev/docs/reference/i18n
package/index.ts ADDED
@@ -0,0 +1,253 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import {
3
+ existsSync,
4
+ mkdirSync,
5
+ readdirSync,
6
+ readFileSync,
7
+ writeFileSync,
8
+ } from "node:fs";
9
+ import { join, relative } from "node:path";
10
+ import type { GrimoirePlugin } from "@sigil-dev/grimoire";
11
+ import { __setLocaleProvider, type Messages, negotiate } from "./runtime.ts";
12
+
13
+ export {
14
+ __setLocaleProvider,
15
+ createI18n,
16
+ type I18n,
17
+ type Key,
18
+ type Messages,
19
+ negotiate,
20
+ type Params,
21
+ type Plural,
22
+ } from "./runtime.ts";
23
+
24
+ export interface I18nOptions {
25
+ /** The language every other one falls back to; its file must exist. Default "en". */
26
+ default?: string;
27
+ /** Where the message files are: one `<locale>.json` each. Default `src/locales`. */
28
+ dir?: string;
29
+ /** The cookie a chosen language is kept in. Default "locale". */
30
+ cookie?: string;
31
+ }
32
+
33
+ export type I18nPlugin = GrimoirePlugin<{ locale: string }>;
34
+
35
+ const RTL = new Set(["ar", "he", "fa", "ur", "ps", "yi", "dv"]);
36
+
37
+ /** Every text's key, as dot paths: what a language has to translate. */
38
+ export function keysOf(messages: Messages, prefix = ""): string[] {
39
+ return Object.entries(messages).flatMap(([k, v]) => {
40
+ const key = prefix + k;
41
+ if (
42
+ typeof v === "string" ||
43
+ (v &&
44
+ typeof v === "object" &&
45
+ typeof (v as { other?: unknown }).other === "string")
46
+ )
47
+ return [key];
48
+ return v && typeof v === "object" ? keysOf(v as Messages, `${key}.`) : [];
49
+ });
50
+ }
51
+
52
+ const IDENT = /^[A-Za-z_$][\w$]*$/;
53
+ const holes = (text: string) =>
54
+ [...text.matchAll(/\{(\w+)\}/g)].map((h) => h[1]!);
55
+ const doc = (text: string) =>
56
+ `/** ${text.replace(/\*\//g, "*\\/").replace(/\s+/g, " ")} */`;
57
+
58
+ /**
59
+ * `m`, from the default language's messages: a getter per text without
60
+ * holes, a function with typed params per text with them, and nested
61
+ * objects for nested keys. The default text is each one's doc comment, so
62
+ * it shows on hover.
63
+ */
64
+ export function messagesCode(
65
+ messages: Messages,
66
+ indent = "\t",
67
+ prefix = "",
68
+ ): string {
69
+ const lines: string[] = [];
70
+ for (const [k, v] of Object.entries(messages)) {
71
+ const key = prefix + k;
72
+ const prop = IDENT.test(k) ? k : JSON.stringify(k);
73
+ const plural =
74
+ v &&
75
+ typeof v === "object" &&
76
+ typeof (v as { other?: unknown }).other === "string";
77
+ if (typeof v === "string" || plural) {
78
+ const texts =
79
+ typeof v === "string"
80
+ ? [v]
81
+ : (Object.values(v as Record<string, string>) as string[]);
82
+ const names = [...new Set(texts.flatMap(holes))].filter(
83
+ (n) => n !== "count",
84
+ );
85
+ const params = [
86
+ ...(plural ? ["count: number"] : []),
87
+ ...names.map(
88
+ (n) =>
89
+ `${IDENT.test(n) ? n : JSON.stringify(n)}: string | number | Date`,
90
+ ),
91
+ ];
92
+ const comment = doc(typeof v === "string" ? v : texts.join(" / "));
93
+ if (params.length === 0) {
94
+ lines.push(
95
+ `${indent}${comment}`,
96
+ `${indent}get ${prop}(): string {`,
97
+ `${indent}\treturn __t(${JSON.stringify(key)});`,
98
+ `${indent}},`,
99
+ );
100
+ } else {
101
+ lines.push(
102
+ `${indent}${comment}`,
103
+ `${indent}${prop}: (params: { ${params.join("; ")} }): string => __t(${JSON.stringify(key)}, params),`,
104
+ );
105
+ }
106
+ } else if (v && typeof v === "object") {
107
+ lines.push(
108
+ `${indent}${prop}: {`,
109
+ messagesCode(v as Messages, `${indent}\t`, `${key}.`),
110
+ `${indent}},`,
111
+ );
112
+ }
113
+ }
114
+ return lines.join("\n");
115
+ }
116
+
117
+ const glue = (
118
+ dir: string,
119
+ locales: string[],
120
+ fallback: string,
121
+ cookie: string,
122
+ messages: Messages,
123
+ ) => {
124
+ const imports = locales
125
+ .map((l, i) => `import m${i} from "${dir}/${l}.json";`)
126
+ .join("\n");
127
+ const entries = locales
128
+ .map((l, i) => `\t\t${JSON.stringify(l)}: m${i},`)
129
+ .join("\n");
130
+ const main = locales.indexOf(fallback);
131
+ return `// Generated by @sigil-dev/i18n from the files in src/locales. Edit those, not this.
132
+ import { createI18n } from "@sigil-dev/i18n/runtime";
133
+ ${imports}
134
+
135
+ export const i18n = createI18n<typeof m${main}>({
136
+ default: ${JSON.stringify(fallback)},
137
+ cookie: ${JSON.stringify(cookie)},
138
+ messages: {
139
+ ${entries}
140
+ },
141
+ });
142
+
143
+ // untyped inside: each message below is typed on its own
144
+ const __t = i18n.translate as (key: string, params?: Record<string, unknown>) => string;
145
+
146
+ /** Every message: \`m.nav.home\`, \`m.hello({ name })\`. In the current language whenever it is read. */
147
+ export const m = {
148
+ ${messagesCode(messages)}
149
+ };
150
+
151
+ /** A message by a key built at runtime, \`translate("status." + order.status)\`; otherwise use \`m\`. */
152
+ export const { translate, locale, locales, defaultLocale, formatDate, formatNumber, formatList, setLocale } = i18n;
153
+ `;
154
+ };
155
+
156
+ /**
157
+ * Languages for the app: messages in `src/locales/<locale>.json`, `t` from
158
+ * `$i18n` in any component or server file, and each request served in the
159
+ * visitor's language.
160
+ *
161
+ * The language is, in order: the first segment of the path when it names
162
+ * one (`/sr-Latn/about`, with `[[lang]]` routes), the `locale` cookie that
163
+ * setLocale() writes, the browser's Accept-Language, and the default.
164
+ */
165
+ export function i18n(options: I18nOptions = {}): I18nPlugin {
166
+ const fallback = options.default ?? "en";
167
+ const cookie = options.cookie ?? "locale";
168
+ const dirOption = options.dir ?? "src/locales";
169
+ let locales: string[] = [fallback];
170
+ const current = new AsyncLocalStorage<string>();
171
+ __setLocaleProvider(() => current.getStore());
172
+
173
+ const detect = (request: Request): string => {
174
+ const url = new URL(request.url);
175
+ const first = decodeURIComponent(url.pathname.split("/")[1] ?? "");
176
+ if (locales.includes(first)) return first;
177
+ const chosen = /(?:^|;\s*)([^=;]+)=([^;]*)/g;
178
+ for (const m of (request.headers.get("cookie") ?? "").matchAll(chosen)) {
179
+ if (m[1]!.trim() !== cookie) continue;
180
+ const value = decodeURIComponent(m[2]!.trim());
181
+ if (locales.includes(value)) return value;
182
+ }
183
+ return (
184
+ negotiate(request.headers.get("accept-language"), locales) ?? fallback
185
+ );
186
+ };
187
+
188
+ return {
189
+ name: "i18n",
190
+ /** Finds the languages, writes `$i18n`, and says what each one is missing. */
191
+ config(config) {
192
+ const root = process.cwd();
193
+ const dir = join(root, dirOption);
194
+ const found = existsSync(dir)
195
+ ? readdirSync(dir)
196
+ .filter((f) => f.endsWith(".json"))
197
+ .map((f) => f.slice(0, -5))
198
+ .sort()
199
+ : [];
200
+ if (!found.includes(fallback)) {
201
+ throw new Error(
202
+ `i18n: the default language is ${fallback}, so ${relative(root, join(dir, `${fallback}.json`)).replace(/\\/g, "/")} must exist`,
203
+ );
204
+ }
205
+ locales = [fallback, ...found.filter((l) => l !== fallback)];
206
+ const read = (l: string) =>
207
+ JSON.parse(readFileSync(join(dir, `${l}.json`), "utf8")) as Messages;
208
+ const wanted = keysOf(read(fallback));
209
+ for (const l of locales.slice(1)) {
210
+ const have = new Set(keysOf(read(l)));
211
+ const missing = wanted.filter((k) => !have.has(k));
212
+ if (missing.length) {
213
+ console.warn(
214
+ `[i18n] ${l} is missing ${missing.length} of ${fallback}'s messages, shown in ${fallback} until translated: ` +
215
+ `${missing.slice(0, 8).join(", ")}${missing.length > 8 ? ", …" : ""}`,
216
+ );
217
+ }
218
+ }
219
+ const out = join(root, ".grimoire/i18n");
220
+ mkdirSync(out, { recursive: true });
221
+ const text = glue(
222
+ relative(out, dir).replace(/\\/g, "/"),
223
+ locales,
224
+ fallback,
225
+ cookie,
226
+ read(fallback),
227
+ );
228
+ const file = join(out, "index.ts");
229
+ if (!existsSync(file) || readFileSync(file, "utf8") !== text)
230
+ writeFileSync(file, text);
231
+ return {
232
+ ...config,
233
+ alias: { $i18n: ".grimoire/i18n", ...(config.alias ?? {}) },
234
+ };
235
+ },
236
+ /** Each request runs in its language, so `t` on the server never sees another visitor's. */
237
+ async handle({ event, resolve }) {
238
+ const locale = detect(event.request);
239
+ (event.locals as unknown as { locale: string }).locale = locale;
240
+ return current.run(locale, () => resolve(event));
241
+ },
242
+ /** `<html lang>`: what the browser's `t` reads, and what screen readers and search engines want. */
243
+ rewriteHtml(rewriter, { request }) {
244
+ const locale = detect(request);
245
+ rewriter.on("html", {
246
+ element(el) {
247
+ el.setAttribute("lang", locale);
248
+ if (RTL.has(locale.split("-")[0]!)) el.setAttribute("dir", "rtl");
249
+ },
250
+ });
251
+ },
252
+ } as I18nPlugin;
253
+ }
package/package.json CHANGED
@@ -1,6 +1,37 @@
1
1
  {
2
2
  "name": "@sigil-dev/i18n",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "description": "Languages for Grimoire: messages per locale, typed keys, plurals by the language's own rules, and each request in the visitor's language",
4
+ "license": "MIT",
5
+ "homepage": "https://sigil.cane1712.dev/docs/reference/i18n",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://git.cane1712.dev/sigil/sigil.git",
9
+ "directory": "packages/i18n"
10
+ },
11
+ "module": "index.ts",
12
+ "type": "module",
13
+ "private": false,
14
+ "version": "0.9.32",
15
+ "exports": {
16
+ ".": "./index.ts",
17
+ "./runtime": "./runtime.ts"
18
+ },
19
+ "keywords": [
20
+ "grimoire",
21
+ "sigil",
22
+ "i18n",
23
+ "translation",
24
+ "locale"
25
+ ],
26
+ "files": [
27
+ "*.ts",
28
+ "README.md"
29
+ ],
30
+ "devDependencies": {
31
+ "@types/bun": "latest"
32
+ },
33
+ "peerDependencies": {
34
+ "typescript": "^5",
35
+ "@sigil-dev/grimoire": "0.9.32"
36
+ }
37
+ }
package/runtime.ts ADDED
@@ -0,0 +1,233 @@
1
+ /**
2
+ * Translations, in the browser and on the server alike. No Node APIs here:
3
+ * this module ships to the browser. On the server, the plugin tells it the
4
+ * request's language through `__setLocaleProvider`.
5
+ */
6
+
7
+ /** A message: text with `{name}` holes, or one text per plural form. */
8
+ export type Plural = {
9
+ zero?: string;
10
+ one?: string;
11
+ two?: string;
12
+ few?: string;
13
+ many?: string;
14
+ other: string;
15
+ [exact: `=${number}`]: string;
16
+ };
17
+ export type Messages = { [key: string]: string | Plural | Messages };
18
+
19
+ /** Every key of a messages object, as dot paths to its texts: "nav.home", "cart.items". */
20
+ export type Key<T> = {
21
+ [K in keyof T & string]: T[K] extends string
22
+ ? K
23
+ : T[K] extends { other: string }
24
+ ? K
25
+ : `${K}.${Key<T[K]>}`;
26
+ }[keyof T & string];
27
+
28
+ export type Params = Record<string, string | number | Date | null | undefined>;
29
+
30
+ const CATEGORIES = new Set(["zero", "one", "two", "few", "many", "other"]);
31
+
32
+ const isPlural = (v: unknown): v is Plural =>
33
+ !!v &&
34
+ typeof v === "object" &&
35
+ typeof (v as Plural).other === "string" &&
36
+ Object.keys(v as object).every((k) => CATEGORIES.has(k) || /^=\d+$/.test(k));
37
+
38
+ let provider: (() => string | undefined) | null = null;
39
+ /** The server's way to say which language this request is in. */
40
+ export function __setLocaleProvider(fn: () => string | undefined): void {
41
+ provider = fn;
42
+ }
43
+
44
+ export interface I18n<M extends Messages> {
45
+ /**
46
+ * The text for `key` in the current language, holes filled. For a key
47
+ * built at runtime; otherwise `m.nav.home` reads better and checks more.
48
+ */
49
+ translate(key: Key<M>, params?: Params): string;
50
+ /** The current language: the request's on the server, the page's in the browser. */
51
+ locale(): string;
52
+ /** Every language there are messages for, the default first. */
53
+ readonly locales: readonly string[];
54
+ readonly defaultLocale: string;
55
+ formatDate(
56
+ date: Date | number | string,
57
+ options?: Intl.DateTimeFormatOptions,
58
+ ): string;
59
+ formatNumber(n: number, options?: Intl.NumberFormatOptions): string;
60
+ /** "a, b and c", in the current language. */
61
+ formatList(
62
+ items: readonly string[],
63
+ options?: Intl.ListFormatOptions,
64
+ ): string;
65
+ /** Switches language: remembered in a cookie, and the page loads again in it. Browser only. */
66
+ setLocale(locale: string): void;
67
+ }
68
+
69
+ /**
70
+ * The translator for a set of messages, one object per language. The
71
+ * generated `$i18n` module makes it from src/locales; this is the same thing
72
+ * by hand.
73
+ */
74
+ export function createI18n<const M extends Messages>(options: {
75
+ default: string;
76
+ messages: Record<string, M | Messages>;
77
+ cookie?: string;
78
+ }): I18n<M> {
79
+ const all = options.messages as Record<string, Messages>;
80
+ if (!all[options.default]) {
81
+ throw new Error(
82
+ `i18n: no messages for the default language "${options.default}"`,
83
+ );
84
+ }
85
+ const locales = [
86
+ options.default,
87
+ ...Object.keys(all).filter((l) => l !== options.default),
88
+ ];
89
+ const cookie = options.cookie ?? "locale";
90
+ const warned = new Set<string>();
91
+ const plurals = new Map<string, Intl.PluralRules>();
92
+
93
+ const fromPage = (): string | undefined => {
94
+ const lang = globalThis.document?.documentElement?.lang;
95
+ return lang && all[lang] ? lang : undefined;
96
+ };
97
+ let warnedOutside = false;
98
+ const locale = () => {
99
+ const fromRequest = provider?.();
100
+ // on the server, no request means module scope: whoever reads a
101
+ // message there gets the default language, for every visitor after
102
+ if (
103
+ provider &&
104
+ fromRequest === undefined &&
105
+ !warnedOutside &&
106
+ (globalThis as { process?: { env?: Record<string, string | undefined> } })
107
+ .process?.env?.NODE_ENV !== "production"
108
+ ) {
109
+ warnedOutside = true;
110
+ console.warn(
111
+ "[i18n] a message was read outside a request, so in the default language. " +
112
+ "Read messages in components, loads and actions, not at the top of a module.",
113
+ );
114
+ }
115
+ const l = fromRequest ?? fromPage();
116
+ return l && all[l] ? l : options.default;
117
+ };
118
+
119
+ const lookup = (
120
+ messages: Messages | undefined,
121
+ key: string,
122
+ ): string | Plural | undefined => {
123
+ let at: unknown = messages;
124
+ for (const part of key.split(".")) {
125
+ if (!at || typeof at !== "object") return undefined;
126
+ at = (at as Messages)[part];
127
+ }
128
+ return typeof at === "string" || isPlural(at) ? at : undefined;
129
+ };
130
+
131
+ const fill = (text: string, params: Params, lang: string) =>
132
+ text.replace(/\{(\w+)\}/g, (hole, name: string) => {
133
+ const v = params[name];
134
+ if (v === undefined || v === null) return hole;
135
+ if (typeof v === "number") return new Intl.NumberFormat(lang).format(v);
136
+ if (v instanceof Date) return new Intl.DateTimeFormat(lang).format(v);
137
+ return String(v);
138
+ });
139
+
140
+ const t = (key: string, params: Params = {}): string => {
141
+ const lang = locale();
142
+ let found = lookup(all[lang], key);
143
+ let used = lang;
144
+ if (found === undefined && lang !== options.default) {
145
+ found = lookup(all[options.default], key);
146
+ used = options.default;
147
+ }
148
+ if (found === undefined) {
149
+ if (!warned.has(key)) {
150
+ warned.add(key);
151
+ console.warn(
152
+ `[i18n] no message "${key}" in ${lang}${lang === options.default ? "" : ` or ${options.default}`}`,
153
+ );
154
+ }
155
+ return key;
156
+ }
157
+ if (typeof found === "string") return fill(found, params, used);
158
+ const count = Number(params.count ?? 0);
159
+ let rules = plurals.get(used);
160
+ if (!rules) plurals.set(used, (rules = new Intl.PluralRules(used)));
161
+ const form =
162
+ found[`=${count}`] ??
163
+ found[rules.select(count) as keyof Plural] ??
164
+ found.other;
165
+ return fill(form as string, params, used);
166
+ };
167
+
168
+ return {
169
+ translate: t as I18n<M>["translate"],
170
+ locale,
171
+ locales,
172
+ defaultLocale: options.default,
173
+ formatDate: (date, opts) =>
174
+ new Intl.DateTimeFormat(locale(), opts).format(new Date(date)),
175
+ formatNumber: (n, opts) => new Intl.NumberFormat(locale(), opts).format(n),
176
+ formatList: (items, opts) =>
177
+ new Intl.ListFormat(locale(), opts).format(items),
178
+ setLocale(next) {
179
+ if (!all[next])
180
+ throw new Error(
181
+ `i18n: no messages for "${next}"; there are ${locales.join(", ")}`,
182
+ );
183
+ const doc = globalThis.document;
184
+ if (!doc)
185
+ throw new Error(
186
+ "i18n: setLocale() switches the page's language, so it runs in the browser",
187
+ );
188
+ doc.cookie = `${cookie}=${encodeURIComponent(next)}; path=/; max-age=31536000; samesite=lax`;
189
+ // a language in the address wins over the cookie, so change it there too
190
+ const parts = globalThis.location.pathname.split("/");
191
+ if (parts[1] && all[parts[1]]) {
192
+ parts[1] = next;
193
+ globalThis.location.assign(
194
+ parts.join("/") + globalThis.location.search,
195
+ );
196
+ } else globalThis.location.reload();
197
+ },
198
+ };
199
+ }
200
+
201
+ /**
202
+ * The best of `available` for an Accept-Language header: exact matches
203
+ * first, then the same language in another region or script ("sr" takes
204
+ * the first "sr-…"), in the order the visitor prefers.
205
+ */
206
+ export function negotiate(
207
+ header: string | null,
208
+ available: readonly string[],
209
+ ): string | undefined {
210
+ if (!header) return undefined;
211
+ const wanted = header
212
+ .split(",")
213
+ .map((part, i) => {
214
+ const [tag, ...rest] = part.trim().split(";");
215
+ const q = rest.find((r) => r.trim().startsWith("q="));
216
+ return {
217
+ tag: tag!.trim().toLowerCase(),
218
+ q: q ? Number(q.trim().slice(2)) : 1,
219
+ i,
220
+ };
221
+ })
222
+ .filter((w) => w.tag && w.tag !== "*" && w.q > 0)
223
+ .sort((a, b) => b.q - a.q || a.i - b.i);
224
+ const lower = available.map((a) => a.toLowerCase());
225
+ for (const w of wanted) {
226
+ const exact = lower.indexOf(w.tag);
227
+ if (exact >= 0) return available[exact];
228
+ const base = w.tag.split("-")[0]!;
229
+ const near = lower.findIndex((a) => a === base || a.startsWith(`${base}-`));
230
+ if (near >= 0) return available[near];
231
+ }
232
+ return undefined;
233
+ }