@rivinia/i18n 0.6.0 → 0.7.1
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/CHANGELOG.md +110 -1
- package/README.md +825 -118
- package/cli/rivinia-i18n-keys.mjs +402 -2
- package/fesm2022/rivinia-i18n-ui.mjs +366 -0
- package/fesm2022/rivinia-i18n-ui.mjs.map +1 -0
- package/fesm2022/rivinia-i18n.mjs +30 -4
- package/fesm2022/rivinia-i18n.mjs.map +1 -1
- package/package.json +5 -1
- package/types/rivinia-i18n-ui.d.ts +112 -0
- package/types/rivinia-i18n.d.ts +66 -11
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rivinia/i18n",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.1",
|
|
4
4
|
"description": "Headless Angular language manager: signals, RTL, SSR-safe loaders, fallback language, missing-key reporting, ICU plurals, typed keys.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"angular",
|
|
@@ -50,6 +50,10 @@
|
|
|
50
50
|
".": {
|
|
51
51
|
"types": "./types/rivinia-i18n.d.ts",
|
|
52
52
|
"default": "./fesm2022/rivinia-i18n.mjs"
|
|
53
|
+
},
|
|
54
|
+
"./ui": {
|
|
55
|
+
"types": "./types/rivinia-i18n-ui.d.ts",
|
|
56
|
+
"default": "./fesm2022/rivinia-i18n-ui.mjs"
|
|
53
57
|
}
|
|
54
58
|
},
|
|
55
59
|
"type": "module",
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
import { Direction } from "@rivinia/i18n";
|
|
2
|
+
import * as i0 from "@angular/core";
|
|
3
|
+
import { TemplateRef } from "@angular/core";
|
|
4
|
+
/** The slice of a language entry the toggle needs. Structurally satisfied by
|
|
5
|
+
* `Language` from @rivinia/i18n (which requires `dir`). */
|
|
6
|
+
interface LanguageLike {
|
|
7
|
+
readonly id: string;
|
|
8
|
+
readonly nativeName?: string;
|
|
9
|
+
readonly dir?: Direction;
|
|
10
|
+
readonly locale?: string;
|
|
11
|
+
}
|
|
12
|
+
/** The structural slice of `RiviniaI18n` the toggle drives (D30 shape).
|
|
13
|
+
* `RiviniaI18n` satisfies it with no import from core at runtime. */
|
|
14
|
+
interface RiviniaLanguageManager {
|
|
15
|
+
readonly languages: () => readonly LanguageLike[];
|
|
16
|
+
readonly currentLanguage: () => string;
|
|
17
|
+
readonly loadingState: () => 'idle' | 'loading' | 'error';
|
|
18
|
+
setLanguageAsync(id: string): Promise<void>;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* The language toggle: one inner `<button>` that switches to the other language
|
|
22
|
+
* of a two-language manager (or presentational pair). The host is the API; the
|
|
23
|
+
* button owns the name, `lang` and `dir`.
|
|
24
|
+
*/
|
|
25
|
+
export declare class RiviniaLanguageToggle {
|
|
26
|
+
readonly manager: import("@angular/core").InputSignal<RiviniaLanguageManager | undefined>;
|
|
27
|
+
readonly languages: import("@angular/core").InputSignal<readonly LanguageLike[]>;
|
|
28
|
+
readonly current: import("@angular/core").InputSignal<string | undefined>;
|
|
29
|
+
readonly label: import("@angular/core").InputSignal<string | undefined>;
|
|
30
|
+
readonly busy: import("@angular/core").InputSignal<boolean>;
|
|
31
|
+
readonly disabled: import("@angular/core").InputSignal<boolean>;
|
|
32
|
+
/** Replaces the default globe. Rendered as-is, so size it with the icon box. */
|
|
33
|
+
readonly icon: import("@angular/core").InputSignal<TemplateRef<unknown> | null>;
|
|
34
|
+
readonly languageChange: import("@angular/core").OutputEmitterRef<string>;
|
|
35
|
+
readonly template: import("@angular/core").Signal<TemplateRef<any> | undefined>;
|
|
36
|
+
private readonly slot;
|
|
37
|
+
private readonly iconSlot;
|
|
38
|
+
private readonly sourceLanguages;
|
|
39
|
+
readonly languageCount: import("@angular/core").Signal<number>;
|
|
40
|
+
readonly manyLanguages: import("@angular/core").Signal<boolean>;
|
|
41
|
+
private readonly currentId;
|
|
42
|
+
/** The language activating the button switches to; `undefined` when nothing renders. */
|
|
43
|
+
readonly target: import("@angular/core").Signal<LanguageLike | undefined>;
|
|
44
|
+
readonly isBusy: import("@angular/core").Signal<boolean>;
|
|
45
|
+
readonly visibleName: import("@angular/core").Signal<string>;
|
|
46
|
+
readonly accessibleName: import("@angular/core").Signal<string>;
|
|
47
|
+
readonly dataLanguages: import("@angular/core").Signal<"2" | "many" | null>;
|
|
48
|
+
private rendered;
|
|
49
|
+
private renderedIcon;
|
|
50
|
+
private warnedMany;
|
|
51
|
+
private warnedLabel;
|
|
52
|
+
ngAfterViewChecked(): void;
|
|
53
|
+
activate(targetId: string): Promise<void>;
|
|
54
|
+
private warn;
|
|
55
|
+
private renderIcon;
|
|
56
|
+
private renderTrigger;
|
|
57
|
+
static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaLanguageToggle, never>;
|
|
58
|
+
static ɵcmp: i0.ɵɵComponentDeclaration<RiviniaLanguageToggle, "rv-language-toggle", never, {
|
|
59
|
+
"manager": {
|
|
60
|
+
"alias": "manager";
|
|
61
|
+
"required": false;
|
|
62
|
+
"isSignal": true;
|
|
63
|
+
};
|
|
64
|
+
"languages": {
|
|
65
|
+
"alias": "languages";
|
|
66
|
+
"required": false;
|
|
67
|
+
"isSignal": true;
|
|
68
|
+
};
|
|
69
|
+
"current": {
|
|
70
|
+
"alias": "current";
|
|
71
|
+
"required": false;
|
|
72
|
+
"isSignal": true;
|
|
73
|
+
};
|
|
74
|
+
"label": {
|
|
75
|
+
"alias": "label";
|
|
76
|
+
"required": false;
|
|
77
|
+
"isSignal": true;
|
|
78
|
+
};
|
|
79
|
+
"busy": {
|
|
80
|
+
"alias": "busy";
|
|
81
|
+
"required": false;
|
|
82
|
+
"isSignal": true;
|
|
83
|
+
};
|
|
84
|
+
"disabled": {
|
|
85
|
+
"alias": "disabled";
|
|
86
|
+
"required": false;
|
|
87
|
+
"isSignal": true;
|
|
88
|
+
};
|
|
89
|
+
"icon": {
|
|
90
|
+
"alias": "icon";
|
|
91
|
+
"required": false;
|
|
92
|
+
"isSignal": true;
|
|
93
|
+
};
|
|
94
|
+
}, {
|
|
95
|
+
"languageChange": "languageChange";
|
|
96
|
+
}, ["template"], never, true, never>;
|
|
97
|
+
}
|
|
98
|
+
interface RiviniaLanguageTriggerContext {
|
|
99
|
+
$implicit: LanguageLike;
|
|
100
|
+
busy: boolean;
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* Marks the `<ng-template>` rendered inside the button in place of the default
|
|
104
|
+
* name span. The toggle captures it with `contentChild(..., { read: TemplateRef })`
|
|
105
|
+
* and renders it through `ViewContainerRef`, so the template is created only when
|
|
106
|
+
* the button is — and never on the server beyond the same pass.
|
|
107
|
+
*/
|
|
108
|
+
export declare class RiviniaLanguageTrigger {
|
|
109
|
+
static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaLanguageTrigger, never>;
|
|
110
|
+
static ɵdir: i0.ɵɵDirectiveDeclaration<RiviniaLanguageTrigger, "[rvLanguageTrigger]", never, {}, {}, never, never, true, never>;
|
|
111
|
+
}
|
|
112
|
+
export type { LanguageLike, RiviniaLanguageManager, RiviniaLanguageTriggerContext };
|
package/types/rivinia-i18n.d.ts
CHANGED
|
@@ -123,7 +123,13 @@ interface MissingParamEvent<T extends string = string> {
|
|
|
123
123
|
*/
|
|
124
124
|
interface RiviniaI18nConfig<T extends string = string> {
|
|
125
125
|
readonly languages: readonly Language<T>[];
|
|
126
|
-
|
|
126
|
+
/**
|
|
127
|
+
* Language used on a first visit (no stored preference, detection off).
|
|
128
|
+
* Defaults to the first entry of `languages`. When provided it must be a
|
|
129
|
+
* non-empty id present in `languages` — anything else throws at construction
|
|
130
|
+
* instead of resolving to an undefined language.
|
|
131
|
+
*/
|
|
132
|
+
readonly defaultLanguage?: T;
|
|
127
133
|
/**
|
|
128
134
|
* Language used when a key is absent from the current dictionary. Must be
|
|
129
135
|
* one of `languages`. The fallback dictionary is loaded silently (it never
|
|
@@ -146,6 +152,13 @@ interface RiviniaI18nConfig<T extends string = string> {
|
|
|
146
152
|
readonly switchStrategy?: SwitchStrategy;
|
|
147
153
|
/** Called when a dictionary load fails. The service still falls back safely. */
|
|
148
154
|
readonly onLoadError?: (language: T, error: unknown) => void;
|
|
155
|
+
/**
|
|
156
|
+
* Log a `console.error` when a dictionary fails to load and no `onLoadError`
|
|
157
|
+
* handler is configured. A failed load leaves every key unresolved, so the
|
|
158
|
+
* page renders raw key names; the warning fires once per language per session.
|
|
159
|
+
* @default isDevMode() && !onLoadError
|
|
160
|
+
*/
|
|
161
|
+
readonly warnOnLoadError?: boolean;
|
|
149
162
|
/**
|
|
150
163
|
* Called when `translate()` cannot resolve a key (absent from the current
|
|
151
164
|
* dictionary, from the fallback dictionary, and with no `defaultValue`).
|
|
@@ -332,8 +345,23 @@ export declare class RiviniaI18n<L extends string = string> {
|
|
|
332
345
|
readonly loaderContext: LoaderContext;
|
|
333
346
|
/** Declared before the storage collaborator: it reads this during setup. */
|
|
334
347
|
private readonly _languages;
|
|
348
|
+
/**
|
|
349
|
+
* Resolved before the storage collaborator reads it: the explicit
|
|
350
|
+
* `defaultLanguage`, else the first configured language. A malformed value
|
|
351
|
+
* throws here instead of letting `undefined` become the current language.
|
|
352
|
+
*/
|
|
353
|
+
private readonly _defaultLanguageId;
|
|
335
354
|
private readonly _languageStorage;
|
|
336
355
|
private readonly _currentLanguageId;
|
|
356
|
+
/** Languages already reported by the default load-error warning. */
|
|
357
|
+
private readonly _warnedLoadErrors;
|
|
358
|
+
/**
|
|
359
|
+
* Routes every dictionary load failure to the consumer handler, or — when
|
|
360
|
+
* none is configured — to the dev-mode warning. Warnings are deduped per
|
|
361
|
+
* language because a retry loop would otherwise flood the console; the
|
|
362
|
+
* consumer handler keeps firing per failure for telemetry.
|
|
363
|
+
*/
|
|
364
|
+
private readonly _onDictionaryLoadError;
|
|
337
365
|
private readonly _store;
|
|
338
366
|
private _initialized;
|
|
339
367
|
private readonly _tasks;
|
|
@@ -463,15 +491,38 @@ export declare class RiviniaI18n<L extends string = string> {
|
|
|
463
491
|
static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaI18n<any>, never>;
|
|
464
492
|
static ɵprov: i0.ɵɵInjectableDeclaration<any>;
|
|
465
493
|
}
|
|
494
|
+
/**
|
|
495
|
+
* Type-level scan for a repeated language id. It only sees a tuple, i.e. a
|
|
496
|
+
* `languages` list written inline in the config. A hoisted `const LANGS = […]`
|
|
497
|
+
* widens to an array, where this resolves to `never` — there the runtime check
|
|
498
|
+
* thrown from `RiviniaI18n`'s constructor is the guarantee.
|
|
499
|
+
*/
|
|
500
|
+
type DuplicateLanguageId<T extends readonly {
|
|
501
|
+
readonly id: string;
|
|
502
|
+
}[], Seen extends string = never> = T extends readonly [infer Head extends {
|
|
503
|
+
readonly id: string;
|
|
504
|
+
}, ...infer Rest extends readonly {
|
|
505
|
+
readonly id: string;
|
|
506
|
+
}[]] ? Head['id'] extends Seen ? Head['id'] | DuplicateLanguageId<Rest, Seen | Head['id']> : DuplicateLanguageId<Rest, Seen | Head['id']> : never;
|
|
507
|
+
type AssertUniqueLanguageIds<T extends readonly {
|
|
508
|
+
readonly id: string;
|
|
509
|
+
}[]> = DuplicateLanguageId<T> extends (infer Duplicate) ? [Duplicate] extends [never] ? unknown : {
|
|
510
|
+
readonly duplicateLanguageId: Duplicate;
|
|
511
|
+
} : never;
|
|
466
512
|
/**
|
|
467
513
|
* Configures `@rivinia/i18n` for the application. Call once at bootstrap.
|
|
468
514
|
* Also registers an app initializer that loads the initial language before
|
|
469
515
|
* first paint (opt out with `preload: false`).
|
|
470
516
|
*
|
|
517
|
+
* A repeated id written inline (`languages: [AR, EN, AR]`) is a compile error.
|
|
518
|
+
* The check needs the array literal, so it is skipped when the call supplies
|
|
519
|
+
* the language union explicitly (`<'ar' | 'en'>`) or passes a hoisted list —
|
|
520
|
+
* both still fail at bootstrap with the runtime error. `Language` in TS terms
|
|
521
|
+
* (not this guard) is what requires `dir`.
|
|
522
|
+
*
|
|
471
523
|
* @example
|
|
472
524
|
* ```ts
|
|
473
525
|
* provideRiviniaI18n({
|
|
474
|
-
* defaultLanguage: 'ar',
|
|
475
526
|
* languages: [
|
|
476
527
|
* { id: 'ar', nativeName: 'العربية', dir: 'rtl' },
|
|
477
528
|
* { id: 'en', nativeName: 'English', dir: 'ltr' },
|
|
@@ -481,25 +532,29 @@ export declare class RiviniaI18n<L extends string = string> {
|
|
|
481
532
|
*
|
|
482
533
|
* @example
|
|
483
534
|
* ```ts
|
|
484
|
-
*
|
|
485
|
-
*
|
|
486
|
-
*
|
|
487
|
-
*
|
|
535
|
+
* // `as const` keeps `id` and `dir` literal — hoisted objects would
|
|
536
|
+
* // otherwise widen to `string` and fail the `Language` check.
|
|
537
|
+
* const AR = { id: 'ar', nativeName: 'العربية', dir: 'rtl' } as const;
|
|
538
|
+
* const EN = { id: 'en', nativeName: 'English', dir: 'ltr' } as const;
|
|
539
|
+
* provideRiviniaI18n<'ar' | 'en'>({
|
|
488
540
|
* languages: [AR, EN],
|
|
489
541
|
* })
|
|
490
542
|
* ```
|
|
491
543
|
*/
|
|
492
|
-
export declare function provideRiviniaI18n<L extends string>(config: RiviniaI18nConfig<L>): EnvironmentProviders;
|
|
544
|
+
export declare function provideRiviniaI18n<L extends string, const C extends RiviniaI18nConfig<L> = RiviniaI18nConfig<L>>(config: C & AssertUniqueLanguageIds<C['languages']> & RiviniaI18nConfig<L>): EnvironmentProviders;
|
|
493
545
|
/** Shorthand for `inject(RiviniaI18n)` — preserves the configured language union. */
|
|
494
546
|
export declare function injectRiviniaI18n<L extends string = string>(): RiviniaI18n<L>;
|
|
495
547
|
/**
|
|
496
548
|
* Binds a config and its typed accessors together so `L` is inferred once
|
|
497
549
|
* from the configuration instead of being lost at the injection site.
|
|
498
550
|
*
|
|
551
|
+
* Like `provideRiviniaI18n`, a repeated id in an inline `languages` list is a
|
|
552
|
+
* compile error; supplying the union explicitly or hoisting the list keeps the
|
|
553
|
+
* runtime check as the guard.
|
|
554
|
+
*
|
|
499
555
|
* @example
|
|
500
556
|
* ```ts
|
|
501
557
|
* export const i18n = defineRiviniaI18n({
|
|
502
|
-
* defaultLanguage: 'ar',
|
|
503
558
|
* languages: [
|
|
504
559
|
* { id: 'ar', nativeName: 'العربية', dir: 'rtl' },
|
|
505
560
|
* { id: 'en', nativeName: 'English', dir: 'ltr' },
|
|
@@ -511,10 +566,10 @@ export declare function injectRiviniaI18n<L extends string = string>(): RiviniaI
|
|
|
511
566
|
* const lang = i18n.inject();
|
|
512
567
|
* ```
|
|
513
568
|
*/
|
|
514
|
-
export declare function defineRiviniaI18n<L extends string>(config: RiviniaI18nConfig<L>): {
|
|
515
|
-
readonly config:
|
|
569
|
+
export declare function defineRiviniaI18n<L extends string, const C extends RiviniaI18nConfig<L> = RiviniaI18nConfig<L>>(config: C & AssertUniqueLanguageIds<C['languages']> & RiviniaI18nConfig<L>): {
|
|
570
|
+
readonly config: C;
|
|
516
571
|
provide: () => EnvironmentProviders;
|
|
517
|
-
inject: () => RiviniaI18n<
|
|
572
|
+
inject: () => RiviniaI18n<C['languages'][number]['id']>;
|
|
518
573
|
};
|
|
519
574
|
/**
|
|
520
575
|
* Progressive-enhancement wrapper around the View Transition API.
|