@8bitscript/i18n 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 8BitScript 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,79 @@
+# @8bitscript/i18n
+
+What the build's locale is like, decided at compile time — the same on
+every target, VIC-20, C64, PET, C128, Atari 8-bit, NES, Commander X16,
+MEGA65, and web. Two import paths: the facts, and a number printed with
+them.
+
+```bash
+pnpm add @8bitscript/i18n
+```
+
+```
+import { Locale } from "@8bitscript/i18n";          // the facts: two ASCII codes
+import { number } from "@8bitscript/i18n/number";   // a grouped number, through @8bitscript/text
+
+text.putChar(cell, Locale.DECIMAL);   // '.' — or ',' in a German build
+number.print(cell, score, 6);         // "12,345" — or "12.345"
+```
+
+| Name | What it is |
+| --- | --- |
+| `Locale.DECIMAL` | The character between a number's whole and fractional parts, as the ASCII code `text.putChar` takes: `.` (46), or `,` (44) |
+| `Locale.GROUP` | The character between groups of three digits: `,` (44), `.` (46), or a space (32) |
+| `number.print(cell, value, width)` | `value` as decimal digits with `Locale.GROUP` every three from the right, right-aligned in `width` cells from `cell`, blank ahead of it. Six cells hold the widest `usmallint`, `65,535`; a narrower field prints the whole number from `cell` rather than cutting it |
+
+## How a locale gets in
+
+A locale is a build input, never a run-time one: `8bs build --locale de`,
+a target's `locale`, or a `release` entry's (see
+[Project config](../../docs/config.md#one-binary-per-locale)). This
+package is one file per locale — `src/index.8bs` for a build that names
+none, `index.de.8bs`, `index.fr.8bs`, `index.it.8bs`, `index.nl.8bs`,
+`index.pt-br.8bs` beside it — and the compiler's resolver picks the file
+by the same twin rule that takes a program's own `strings.de.8bs` over its
+`strings.8bs`. Nothing in a program names a locale; nothing is looked up
+while it runs; a program that reads neither name links none of this.
+
+A locale with no file here silently reads the plain one — `--locale sv`
+gets `.` and `,`. Add a twin (five lines; cite the CLDR entry, as each of
+the shipped ones does) rather than branch on `#locale("sv")` in a program.
+Spanish is deliberately not shipped yet: CLDR gives `es` a
+`minimumGroupingDigits` of 2, so a four-digit number is written `1234`
+and only `12.345` is grouped — a rule `number.print` does not express,
+and a twin that said `.` alone would print `1.234`. Check the key in
+CLDR's `numbers.json` for `es` before adding it.
+
+## What is here, and what is not
+
+The two facts are the ones a program on a character grid can act on.
+Every value is a literal in the portable character set — `,` `.` and the
+space are on every machine, including the NES's own font — so a build
+never reaches for a glyph its target cannot draw. A read of one folds to
+the literal: a PET, VIC-20 or C64 program that writes `Locale.GROUP` is
+byte-identical to one that writes `44` (a test builds both and compares
+the images). Nothing here is a
+string: a program's strings are its own, in a `strings.8bs` and that
+file's locale twins, where the compiler can see their lengths. Nothing
+here names an accented letter or a currency sign, because no target can
+show one; a language written in them is transliterated in the program's
+strings file (`DRUECKEN`), the way a typewriter without the keys spelled
+it, and that is a decision the program's author makes line by line.
+
+`number.print` is code — the place-value loop every machine's
+`text.printNumber` uses to find digits without a divide, plus the
+separator — and lives at its own subpath so that a program printing a
+zero-padded HUD field (`text.printNumber`, or a `${score:5}` template)
+carries none of it. What it costs, measured 2026-09-17 as one number
+printed this way instead of with `text.printNumber`, in a program that
+owns its machine: +209 bytes and +11 of RAM on the PET, +202 and +11 on
+the unexpanded VIC-20, +194 and +9 on the C64. The two are for different
+numbers: `printNumber` is the counter that must never shift columns,
+this is the total the player reads.
+
+Tests: `pnpm --filter @8bitscript/i18n test` — resolution per locale on
+every machine, a clean link on all nine with and without a locale, the
+PET and VIC-20 images built for real (the fact byte-identical to its
+literal; `number.print`'s frame inside their zero page), and
+`number.print` built and run for the web, its cells read back, in
+English and in German.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@8bitscript/i18n",
+  "version": "0.13.0",
+  "description": "What a locale is like, decided at compile time: the bare import is the build's locale's own facts — its decimal and grouping separators — as a twin file per locale inside the package, so a program reads Locale.GROUP and the build picks the file; ./number prints a grouped number through @8bitscript/text with them. Costs nothing where it is not read.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/8BitScript/8bitscript.git",
+    "directory": "packages/i18n"
+  },
+  "8bitscript": {
+    "entry": "./src/index.8bs",
+    "exports": {
+      "./number": "./src/number.8bs"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@8bitscript/text": "workspace:*"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.8bs

@@ -0,0 +1,29 @@
+// @8bitscript/i18n — what the build's locale is like, as compile-time
+// facts. This file is the one a build with no locale named reads: the
+// program's source language, which for every program so far has been
+// English, so the numbers below are English's. Beside it, index.de.8bs
+// and the rest are one locale each, and `8bs build --locale de` (or a
+// target's `locale`, or a `release` entry's) takes that file instead —
+// the resolver's locale twin rule, the same one that takes a program's
+// own strings.de.8bs over its strings.8bs (docs/config.md, "One binary
+// per locale"). A locale with no file here reads this one, silently:
+// add the twin (five lines) rather than branch on #locale("...").
+//
+// Every value is a literal in a namespace, so a read of Locale.GROUP is
+// one byte in the image and a branch on it folds; a program that never
+// reads it links none of this. What is here is what a program on a
+// character grid can act on: the two separators a number is written
+// with, as the ASCII codes @8bitscript/text's putChar takes. Both are
+// in the portable character set on every machine (`,` and `.`; a space
+// where a language groups with one). What is not here is anything the
+// machines cannot show — an accented letter, a currency sign — and
+// anything that is a string: strings are the program's own, in its
+// strings.8bs and that file's locale twins.
+//
+// Sources: CLDR's number symbols for each locale (unicode.org/cldr);
+// each twin cites the entry it was read from.
+
+export namespace Locale {
+    const DECIMAL: utinyint = 46; // '.' — 3.5
+    const GROUP: utinyint = 44;   // ',' — 65,535
+}

package/src/index.de.8bs

@@ -0,0 +1,6 @@
+// German — index.8bs's twin for `--locale de`. CLDR de: decimal ",",
+// group "." (1.234,5).
+export namespace Locale {
+    const DECIMAL: utinyint = 44; // ','
+    const GROUP: utinyint = 46;   // '.'
+}

package/src/index.fr.8bs

@@ -0,0 +1,7 @@
+// French — index.8bs's twin for `--locale fr`. CLDR fr: decimal ",",
+// group U+202F narrow no-break space (1 234,5); a character grid has one
+// space, so it is 32.
+export namespace Locale {
+    const DECIMAL: utinyint = 44; // ','
+    const GROUP: utinyint = 32;   // ' '
+}

package/src/index.it.8bs

@@ -0,0 +1,6 @@
+// Italian — index.8bs's twin for `--locale it`. CLDR it: decimal ",",
+// group "." (1.234,5).
+export namespace Locale {
+    const DECIMAL: utinyint = 44; // ','
+    const GROUP: utinyint = 46;   // '.'
+}

package/src/index.nl.8bs

@@ -0,0 +1,6 @@
+// Dutch — index.8bs's twin for `--locale nl`. CLDR nl: decimal ",",
+// group "." (1.234,5).
+export namespace Locale {
+    const DECIMAL: utinyint = 44; // ','
+    const GROUP: utinyint = 46;   // '.'
+}

package/src/index.pt-br.8bs

@@ -0,0 +1,6 @@
+// Brazilian Portuguese — index.8bs's twin for `--locale pt-br`. CLDR
+// pt-BR: decimal ",", group "." (1.234,5).
+export namespace Locale {
+    const DECIMAL: utinyint = 44; // ','
+    const GROUP: utinyint = 46;   // '.'
+}

package/src/number.8bs

@@ -0,0 +1,75 @@
+// @8bitscript/i18n/number — a number the way the build's locale writes
+// it, through @8bitscript/text: `number.print(cell, value, width)` writes
+// `value` as decimal digits with Locale.GROUP between every three, from
+// the right, right-aligned in a field of `width` cells from `cell`, the
+// cells ahead of it blank — "1,234" in an English build and "1.234" in a
+// German one, from the same call. The most a usmallint takes is six
+// cells ("65,535"); a field narrower than its number is printed from
+// `cell` anyway, so the number is never cut, and a caller that sizes the
+// field at six is safe for every value.
+//
+// Opt-in, at its own subpath: unlike the facts at the bare import this is
+// code — a loop over the place values, the way every machine's
+// text.printNumber works out digits without a divide (the 6502 has none,
+// and `value / 10` would link a 250-byte routine) — and a program that
+// prints its numbers as `text.printNumber`'s zero-padded field, or in a
+// template, pays nothing for it. text.printNumber is the field for a HUD
+// counter that must not shift columns; this is the number for a total
+// the player reads.
+import { text } from "@8bitscript/text";
+import { Locale } from "./index.8bs";
+
+const PLACES: array<usmallint, 5> = [10000, 1000, 100, 10, 1];
+
+// Written for a small zero-page frame — the 6502 backend keeps every
+// local and parameter of the deepest call chain in zero page, so a local
+// here is a byte of every program's tightest budget: a first cut with
+// four locals for the digit count and the field needed 19 bytes, this
+// one 15 (text.printNumber's own is 13). `cell` is the cursor, and
+// `remaining` is the digit count, the number's width, and the countdown
+// to the separator in turn. What the whole thing costs, measured
+// 2026-09-17 as one number printed this way instead of with
+// text.printNumber, in a program that owns its machine: +209 bytes and
+// +11 of RAM on the PET, +202 and +11 on the unexpanded VIC-20, +194 and
+// +9 on the C64 — @8bitscript/text's fill() and putChar() linked beside
+// its place(), and the separator's own loop.
+export namespace number {
+    function print(cell: usmallint, value: usmallint, width: utinyint): void {
+        // How many digits: the first place the value reaches, high to
+        // low — one digit for 0-9, so a zero prints as one "0".
+        let remaining: utinyint = 1;
+        let i: utinyint = 0;
+        while (i < 4) {
+            if (remaining == 1 && value >= PLACES[i]) {
+                remaining = 5 - i;
+            }
+            i++;
+        }
+        // Five digits at most, so at most one separator, and only when
+        // there is a fourth digit: the number's width is one more then.
+        i = remaining;
+        if (remaining > 3) {
+            i = remaining + 1;
+        }
+        if (width > i) {
+            text.fill(cell, width - i, 32);
+            cell = cell + (width - i);
+        }
+        i = 5 - remaining; // the first place printed
+        while (i < 5) {
+            let digit: utinyint = 48; // '0'
+            while (value >= PLACES[i]) {
+                value = value - PLACES[i];
+                digit++;
+            }
+            text.putChar(cell, digit);
+            cell++;
+            remaining--;
+            if (remaining == 3) {
+                text.putChar(cell, Locale.GROUP);
+                cell++;
+            }
+            i++;
+        }
+    }
+}