@baukit/localization-core 0.2.1 → 0.3.0

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.
package/README.md CHANGED
@@ -7,6 +7,30 @@ supported locale list, fallback locale, translation catalogs, and copy.
7
7
  i18next and React composition stays in the consuming app. Resolve and hydrate the locale before
8
8
  rendering localized UI, then pass that resolved locale to this package's formatter factories.
9
9
 
10
+ ## Typed catalog segments
11
+
12
+ `defineCatalogSegment` uses one product-selected reference locale to type every translation. The
13
+ supported locale tuple stays in the product. TypeScript rejects missing or extra locale keys,
14
+ missing or extra message keys, and a translation that changes a string into a plural message.
15
+
16
+ ```ts
17
+ import { defineCatalogSegment } from '@baukit/localization-core';
18
+
19
+ const accountCatalogs = defineCatalogSegment(
20
+ ['en', 'de'] as const,
21
+ 'en',
22
+ { title: 'Account', devices: { one: '1 device', other: '{{count}} devices' } },
23
+ {
24
+ de: { title: 'Konto', devices: { one: '1 Gerät', other: '{{count}} Geräte' } },
25
+ },
26
+ );
27
+ ```
28
+
29
+ Existing catalog objects can move one segment at a time. Pass the current locale list, reference
30
+ locale, reference segment, and translations to `defineCatalogSegment`. Keep translation loading,
31
+ i18next resources, namespaces, and copy in the product. The function freezes the returned locale
32
+ map but does not deep-freeze or inspect message text.
33
+
10
34
  ## Civil dates
11
35
 
12
36
  A civil date is a `YYYY-MM-DD` calendar day with no time and no offset. Diary entries, plan days,
@@ -37,8 +61,8 @@ addCivilDays('2026-03-07', 1); // '2026-03-08', DST does not shift a calendar da
37
61
  ## Boundaries
38
62
 
39
63
  The package does not include translations, product catalog IDs, persistence, React providers, Expo
40
- Localization, or a localization library. It also does not choose plural or unit policy for an
41
- application.
64
+ Localization, or a localization library. It defines a string plus `{ one, other }` plural shape for
65
+ typed catalog segments, but the application still owns plural rules and interpolation syntax.
42
66
 
43
67
  Every function that depends on a locale or a time zone takes it as an argument. `resolvedTimeZone()`
44
68
  is the one reader of host state, and it is a separate call you make deliberately. That is what keeps
@@ -0,0 +1,18 @@
1
+ export interface PluralMessage {
2
+ readonly one: string;
3
+ readonly other: string;
4
+ }
5
+ export type CatalogMessage = string | PluralMessage;
6
+ export type CatalogSegment = Readonly<Record<string, CatalogMessage>>;
7
+ export type LocalizedCatalogSegment<TCatalog extends CatalogSegment> = {
8
+ readonly [TKey in keyof TCatalog]: TCatalog[TKey] extends string ? string : TCatalog[TKey] extends PluralMessage ? PluralMessage : never;
9
+ };
10
+ export type CatalogSegmentLocales<TLocales extends string, TReferenceLocale extends TLocales, TReferenceCatalog extends CatalogSegment> = Readonly<Record<TReferenceLocale, TReferenceCatalog> & Record<Exclude<TLocales, TReferenceLocale>, LocalizedCatalogSegment<TReferenceCatalog>>>;
11
+ /**
12
+ * Defines one product-owned catalog segment against a reference locale.
13
+ *
14
+ * TypeScript rejects missing or extra locale keys, missing or extra message
15
+ * keys, and translations that change a string into a plural message or back.
16
+ */
17
+ export declare function defineCatalogSegment<const TLocales extends readonly [string, ...string[]], const TReferenceLocale extends TLocales[number], const TReferenceCatalog extends CatalogSegment>(supportedLocales: TLocales, referenceLocale: TReferenceLocale, referenceCatalog: TReferenceCatalog, localizedCatalogs: Readonly<Record<Exclude<TLocales[number], TReferenceLocale>, LocalizedCatalogSegment<TReferenceCatalog>>>): CatalogSegmentLocales<TLocales[number], TReferenceLocale, TReferenceCatalog>;
18
+ //# sourceMappingURL=catalog-segment.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"catalog-segment.d.ts","sourceRoot":"","sources":["../src/catalog-segment.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,aAAa,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAEtE,MAAM,MAAM,uBAAuB,CAAC,QAAQ,SAAS,cAAc,IAAI;IACrE,QAAQ,EAAE,IAAI,IAAI,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,MAAM,GAC5D,MAAM,GACN,QAAQ,CAAC,IAAI,CAAC,SAAS,aAAa,GAClC,aAAa,GACb,KAAK;CACZ,CAAC;AAEF,MAAM,MAAM,qBAAqB,CAC/B,QAAQ,SAAS,MAAM,EACvB,gBAAgB,SAAS,QAAQ,EACjC,iBAAiB,SAAS,cAAc,IACtC,QAAQ,CACV,MAAM,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,GACzC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,gBAAgB,CAAC,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,CAAC,CAC1F,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,CAAC,QAAQ,SAAS,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EACrD,KAAK,CAAC,gBAAgB,SAAS,QAAQ,CAAC,MAAM,CAAC,EAC/C,KAAK,CAAC,iBAAiB,SAAS,cAAc,EAE9C,gBAAgB,EAAE,QAAQ,EAC1B,eAAe,EAAE,gBAAgB,EACjC,gBAAgB,EAAE,iBAAiB,EACnC,iBAAiB,EAAE,QAAQ,CACzB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,CAAC,CAChG,GACA,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,EAAE,iBAAiB,CAAC,CAuB9E"}
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Defines one product-owned catalog segment against a reference locale.
3
+ *
4
+ * TypeScript rejects missing or extra locale keys, missing or extra message
5
+ * keys, and translations that change a string into a plural message or back.
6
+ */
7
+ export function defineCatalogSegment(supportedLocales, referenceLocale, referenceCatalog, localizedCatalogs) {
8
+ if (new Set(supportedLocales).size !== supportedLocales.length) {
9
+ throw new RangeError('Supported locales must not contain duplicates.');
10
+ }
11
+ if (!supportedLocales.includes(referenceLocale)) {
12
+ throw new RangeError('The reference locale must be supported.');
13
+ }
14
+ const expectedLocalizedLocales = supportedLocales.filter((locale) => locale !== referenceLocale);
15
+ const suppliedLocalizedLocales = Object.keys(localizedCatalogs);
16
+ if (suppliedLocalizedLocales.length !== expectedLocalizedLocales.length ||
17
+ expectedLocalizedLocales.some((locale) => !Object.prototype.hasOwnProperty.call(localizedCatalogs, locale))) {
18
+ throw new RangeError('Localized catalogs must match the supported locales.');
19
+ }
20
+ return Object.freeze({
21
+ ...localizedCatalogs,
22
+ [referenceLocale]: referenceCatalog,
23
+ });
24
+ }
25
+ //# sourceMappingURL=catalog-segment.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"catalog-segment.js","sourceRoot":"","sources":["../src/catalog-segment.ts"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAKlC,gBAA0B,EAC1B,eAAiC,EACjC,gBAAmC,EACnC,iBAEC;IAED,IAAI,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,KAAK,gBAAgB,CAAC,MAAM,EAAE,CAAC;QAC/D,MAAM,IAAI,UAAU,CAAC,gDAAgD,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,wBAAwB,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,eAAe,CAAC,CAAC;IACjG,MAAM,wBAAwB,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAChE,IACE,wBAAwB,CAAC,MAAM,KAAK,wBAAwB,CAAC,MAAM;QACnE,wBAAwB,CAAC,IAAI,CAC3B,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAC7E,EACD,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,sDAAsD,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,iBAAiB;QACpB,CAAC,eAAe,CAAC,EAAE,gBAAgB;KACpC,CAAiF,CAAC;AACrF,CAAC"}
package/dist/index.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  export { catalogKeySet, compareCatalogKeys, type CatalogDifference } from './catalog.js';
2
+ export { defineCatalogSegment, type CatalogMessage, type CatalogSegment, type CatalogSegmentLocales, type LocalizedCatalogSegment, type PluralMessage, } from './catalog-segment.js';
2
3
  export { addCivilDays, assertCivilDate, assertCivilTime, assertTimeZone, civilDateForInstant, civilDateValidationCode, civilDaysBetween, civilToday, compareCivilDates, INVALID_CIVIL_DATE_CODE, isCivilDate, isInstantOnCivilDate, parseCivilDate, resolvedTimeZone, type CivilDateParseResult, type CivilDateValidationCode, } from './civil-date.js';
3
4
  export { createLocalizedCodeResolver, type CodeResolverOptions, type LocalizedCodeEntry, } from './codes.js';
4
5
  export { createDateTimeFormatter, createNumberFormatter } from './formatters.js';
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EACvB,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACzF,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EACvB,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,EAC3B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
package/dist/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export { catalogKeySet, compareCatalogKeys } from './catalog.js';
2
+ export { defineCatalogSegment, } from './catalog-segment.js';
2
3
  export { addCivilDays, assertCivilDate, assertCivilTime, assertTimeZone, civilDateForInstant, civilDateValidationCode, civilDaysBetween, civilToday, compareCivilDates, INVALID_CIVIL_DATE_CODE, isCivilDate, isInstantOnCivilDate, parseCivilDate, resolvedTimeZone, } from './civil-date.js';
3
4
  export { createLocalizedCodeResolver, } from './codes.js';
4
5
  export { createDateTimeFormatter, createNumberFormatter } from './formatters.js';
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAA0B,MAAM,cAAc,CAAC;AACzF,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EACvB,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,GAG5B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAyB,MAAM,aAAa,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAA0B,MAAM,cAAc,CAAC;AACzF,OAAO,EACL,oBAAoB,GAMrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,YAAY,EACZ,eAAe,EACf,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,uBAAuB,EACvB,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,2BAA2B,GAG5B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAyB,MAAM,aAAa,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@baukit/localization-core",
3
- "version": "0.2.1",
3
+ "version": "0.3.0",
4
4
  "description": "Dependency-free locale resolution, catalog key comparison, stable-code localization, and explicit-locale Intl formatter factories.",
5
5
  "license": "MIT",
6
6
  "author": "Patrick Koss",
@@ -32,15 +32,14 @@
32
32
  "README.md",
33
33
  "LICENSE"
34
34
  ],
35
+ "devDependencies": {
36
+ "typescript": "6.0.3",
37
+ "vitest": "4.1.10"
38
+ },
35
39
  "scripts": {
36
40
  "build": "tsc -p tsconfig.json",
37
- "prepare": "pnpm run build",
38
41
  "test": "vitest run --config ../../vitest.config.ts",
39
42
  "lint": "eslint src --max-warnings=0",
40
43
  "format:check": "prettier --check src package.json tsconfig.json"
41
- },
42
- "devDependencies": {
43
- "typescript": "6.0.3",
44
- "vitest": "4.1.10"
45
44
  }
46
- }
45
+ }