@veroxm/sdk 1.12.0 → 1.13.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/CHANGELOG.md +17 -0
- package/dist/client.d.ts +3 -0
- package/dist/client.js +2 -0
- package/dist/generated/api.d.ts +248 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/translations.d.ts +106 -0
- package/dist/translations.js +177 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,22 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.13.0
|
|
4
|
+
|
|
5
|
+
- App translations: `app.translations.get('ar')` reads a locale's whole bundle in one request: its texts (nested, or
|
|
6
|
+
dotted keys with `flat`), writing direction (`dir: 'rtl'`), own name ("العربية") and the project's translations
|
|
7
|
+
`version`. Keys not translated yet come from the default locale (`fallback: false` for only the locale's own), and
|
|
8
|
+
`fallback` lists them. `resource('ar')` is the bare texts as i18next loads them; `locales()` lists the project's
|
|
9
|
+
locales with their direction and coverage (`translated` of `total`). Pass `version` for an address that is cached for
|
|
10
|
+
a year. Any key of the project can read them, a browser key too. `fetchTranslations({ baseUrl, projectId, apiKey,
|
|
11
|
+
locale })` and `fetchTranslationLocales(...)` do the same without a `VeroXMApp`.
|
|
12
|
+
- `createTranslator(texts, { locale })` gives `t(key, values)` for those texts, i18next-style: `{{name}}`,
|
|
13
|
+
`{{user.name}}`, `$t(other.key)`, and plural forms by `count` (`items_one`, `items_other`, `items_zero`). A key with
|
|
14
|
+
no text gives the key itself, or the fallback you pass. Needs a VeroXM server with app translations.
|
|
15
|
+
- `VeroxmI18nextBackend`: an i18next backend, `i18next.use(VeroxmI18nextBackend).init({ backend: { baseUrl, projectId,
|
|
16
|
+
apiKey } })`. One request per language; the "translation" namespace gets the whole bundle and another namespace the
|
|
17
|
+
texts under its name. A language the project doesn't have loads as empty, so i18next falls back to `fallbackLng`.
|
|
18
|
+
`fetchTranslationResource(...)` reads the bare texts without a `VeroXMApp`.
|
|
19
|
+
|
|
3
20
|
## 1.12.0
|
|
4
21
|
|
|
5
22
|
- Safe retries for writes: `content(slug).create()`, `update()`, `delete()` and `functions.call()` take an
|
package/dist/client.d.ts
CHANGED
|
@@ -6,6 +6,7 @@ import { FunctionsResource } from './functions.js';
|
|
|
6
6
|
import { TasksResource } from './tasks.js';
|
|
7
7
|
import { ProcessesResource } from './processes.js';
|
|
8
8
|
import { FormsResource } from './forms.js';
|
|
9
|
+
import { TranslationsResource } from './translations.js';
|
|
9
10
|
import { type TokenStorage } from './token-storage.js';
|
|
10
11
|
export interface VeroXMAppOptions {
|
|
11
12
|
/** Your VeroXM deployment's origin, e.g. "https://cms.example.com" -- no trailing /public/... needed, VeroXMApp builds that itself. */
|
|
@@ -43,6 +44,8 @@ export declare class VeroXMApp {
|
|
|
43
44
|
readonly processes: ProcessesResource;
|
|
44
45
|
/** The project's forms and responses (server keys with forms:read). */
|
|
45
46
|
readonly forms: FormsResource;
|
|
47
|
+
/** The project's app translations: a locale's whole bundle in one request (any key, a browser key too). */
|
|
48
|
+
readonly translations: TranslationsResource;
|
|
46
49
|
private readonly apiBase;
|
|
47
50
|
private readonly timeoutMs;
|
|
48
51
|
private readonly retries;
|
package/dist/client.js
CHANGED
|
@@ -7,6 +7,7 @@ import { FunctionsResource } from './functions.js';
|
|
|
7
7
|
import { TasksResource } from './tasks.js';
|
|
8
8
|
import { ProcessesResource } from './processes.js';
|
|
9
9
|
import { FormsResource } from './forms.js';
|
|
10
|
+
import { TranslationsResource } from './translations.js';
|
|
10
11
|
import { MemoryTokenStorage, BrowserLocalStorageTokenStorage } from './token-storage.js';
|
|
11
12
|
function defaultTokenStorage(projectId) {
|
|
12
13
|
if (typeof window !== 'undefined' && typeof window.localStorage !== 'undefined') {
|
|
@@ -29,6 +30,7 @@ export class VeroXMApp {
|
|
|
29
30
|
this.tasks = new TasksResource(this);
|
|
30
31
|
this.processes = new ProcessesResource(this);
|
|
31
32
|
this.forms = new FormsResource(this);
|
|
33
|
+
this.translations = new TranslationsResource(this);
|
|
32
34
|
}
|
|
33
35
|
static initializeApp(options) {
|
|
34
36
|
checkTimeout(options.timeoutMs);
|
package/dist/generated/api.d.ts
CHANGED
|
@@ -1310,6 +1310,86 @@ export interface paths {
|
|
|
1310
1310
|
patch?: never;
|
|
1311
1311
|
trace?: never;
|
|
1312
1312
|
};
|
|
1313
|
+
"/projects/{uuid}/translations": {
|
|
1314
|
+
parameters: {
|
|
1315
|
+
query?: never;
|
|
1316
|
+
header?: never;
|
|
1317
|
+
path?: never;
|
|
1318
|
+
cookie?: never;
|
|
1319
|
+
};
|
|
1320
|
+
/**
|
|
1321
|
+
* The project's locales: names, writing direction and how much is translated
|
|
1322
|
+
* @description Any key of the project, a browser key too. Every answer has an ETag: send it back as If-None-Match and an unchanged answer is a 304 with no body. The project's own address (/projects/{uuid}/...) is cacheable by CDNs; with `v` set to the current version it is cached for a year. The short address (/translations/...) takes the project from the key and is cached by the browser only.
|
|
1323
|
+
*/
|
|
1324
|
+
get: operations["listTranslationLocales"];
|
|
1325
|
+
put?: never;
|
|
1326
|
+
post?: never;
|
|
1327
|
+
delete?: never;
|
|
1328
|
+
options?: never;
|
|
1329
|
+
head?: never;
|
|
1330
|
+
patch?: never;
|
|
1331
|
+
trace?: never;
|
|
1332
|
+
};
|
|
1333
|
+
"/projects/{uuid}/translations/{locale}": {
|
|
1334
|
+
parameters: {
|
|
1335
|
+
query?: never;
|
|
1336
|
+
header?: never;
|
|
1337
|
+
path?: never;
|
|
1338
|
+
cookie?: never;
|
|
1339
|
+
};
|
|
1340
|
+
/**
|
|
1341
|
+
* A locale's app translations
|
|
1342
|
+
* @description Any key of the project, a browser key too. Every answer has an ETag: send it back as If-None-Match and an unchanged answer is a 304 with no body. The project's own address (/projects/{uuid}/...) is cacheable by CDNs; with `v` set to the current version it is cached for a year. The short address (/translations/...) takes the project from the key and is cached by the browser only.
|
|
1343
|
+
*/
|
|
1344
|
+
get: operations["getTranslations"];
|
|
1345
|
+
put?: never;
|
|
1346
|
+
post?: never;
|
|
1347
|
+
delete?: never;
|
|
1348
|
+
options?: never;
|
|
1349
|
+
head?: never;
|
|
1350
|
+
patch?: never;
|
|
1351
|
+
trace?: never;
|
|
1352
|
+
};
|
|
1353
|
+
"/translations": {
|
|
1354
|
+
parameters: {
|
|
1355
|
+
query?: never;
|
|
1356
|
+
header?: never;
|
|
1357
|
+
path?: never;
|
|
1358
|
+
cookie?: never;
|
|
1359
|
+
};
|
|
1360
|
+
/**
|
|
1361
|
+
* The project's locales: names, writing direction and how much is translated
|
|
1362
|
+
* @description Any key of the project, a browser key too. Every answer has an ETag: send it back as If-None-Match and an unchanged answer is a 304 with no body. The project's own address (/projects/{uuid}/...) is cacheable by CDNs; with `v` set to the current version it is cached for a year. The short address (/translations/...) takes the project from the key and is cached by the browser only.
|
|
1363
|
+
*/
|
|
1364
|
+
get: operations["listTranslationLocalesByKey"];
|
|
1365
|
+
put?: never;
|
|
1366
|
+
post?: never;
|
|
1367
|
+
delete?: never;
|
|
1368
|
+
options?: never;
|
|
1369
|
+
head?: never;
|
|
1370
|
+
patch?: never;
|
|
1371
|
+
trace?: never;
|
|
1372
|
+
};
|
|
1373
|
+
"/translations/{locale}": {
|
|
1374
|
+
parameters: {
|
|
1375
|
+
query?: never;
|
|
1376
|
+
header?: never;
|
|
1377
|
+
path?: never;
|
|
1378
|
+
cookie?: never;
|
|
1379
|
+
};
|
|
1380
|
+
/**
|
|
1381
|
+
* A locale's app translations
|
|
1382
|
+
* @description Any key of the project, a browser key too. Every answer has an ETag: send it back as If-None-Match and an unchanged answer is a 304 with no body. The project's own address (/projects/{uuid}/...) is cacheable by CDNs; with `v` set to the current version it is cached for a year. The short address (/translations/...) takes the project from the key and is cached by the browser only.
|
|
1383
|
+
*/
|
|
1384
|
+
get: operations["getTranslationsByKey"];
|
|
1385
|
+
put?: never;
|
|
1386
|
+
post?: never;
|
|
1387
|
+
delete?: never;
|
|
1388
|
+
options?: never;
|
|
1389
|
+
head?: never;
|
|
1390
|
+
patch?: never;
|
|
1391
|
+
trace?: never;
|
|
1392
|
+
};
|
|
1313
1393
|
}
|
|
1314
1394
|
export type webhooks = Record<string, never>;
|
|
1315
1395
|
export interface components {
|
|
@@ -2400,6 +2480,51 @@ export interface components {
|
|
|
2400
2480
|
/** @description Pass as `cursor` for the next page; null at the end. */
|
|
2401
2481
|
next: string | null;
|
|
2402
2482
|
};
|
|
2483
|
+
/** @description Texts by key: nested objects (`{ "checkout": { "pay": "Pay {{amount}}" } }`), or dotted keys with `flat=1`. Texts keep i18next placeholders (`{{name}}`, `$t(key)`). */
|
|
2484
|
+
TranslationTexts: {
|
|
2485
|
+
[key: string]: string | components["schemas"]["TranslationTexts"];
|
|
2486
|
+
};
|
|
2487
|
+
TranslationLocale: {
|
|
2488
|
+
/** @description The locale code, e.g. "ar". */
|
|
2489
|
+
code: string;
|
|
2490
|
+
/** @description The project's name for it ("Arabic"). */
|
|
2491
|
+
name: string;
|
|
2492
|
+
/** @description Its own name ("العربية"). */
|
|
2493
|
+
nativeName: string;
|
|
2494
|
+
/**
|
|
2495
|
+
* @description Writing direction.
|
|
2496
|
+
* @enum {string}
|
|
2497
|
+
*/
|
|
2498
|
+
dir: "rtl" | "ltr";
|
|
2499
|
+
isDefault: boolean;
|
|
2500
|
+
/** @description Keys of the default locale with a text in this one. */
|
|
2501
|
+
translated: number;
|
|
2502
|
+
/** @description Keys of the default locale. */
|
|
2503
|
+
total: number;
|
|
2504
|
+
};
|
|
2505
|
+
TranslationLocales: {
|
|
2506
|
+
/** @description Rises with every change: send it as `v` for an address cached for a year. */
|
|
2507
|
+
version: number;
|
|
2508
|
+
defaultLocale: string;
|
|
2509
|
+
locales: components["schemas"]["TranslationLocale"][];
|
|
2510
|
+
};
|
|
2511
|
+
TranslationBundle: {
|
|
2512
|
+
/** @description The locale answered: "ar" for a request for "ar-SA" when the project has only "ar". */
|
|
2513
|
+
locale: string;
|
|
2514
|
+
name: string;
|
|
2515
|
+
nativeName: string;
|
|
2516
|
+
/** @enum {string} */
|
|
2517
|
+
dir: "rtl" | "ltr";
|
|
2518
|
+
defaultLocale: string;
|
|
2519
|
+
version: number;
|
|
2520
|
+
/** @description Keys in the bundle. */
|
|
2521
|
+
keys: number;
|
|
2522
|
+
/** @description Keys with a text in this locale. */
|
|
2523
|
+
translated: number;
|
|
2524
|
+
/** @description Keys whose text is the default locale's (not translated yet). */
|
|
2525
|
+
fallback: string[];
|
|
2526
|
+
translations: components["schemas"]["TranslationTexts"];
|
|
2527
|
+
};
|
|
2403
2528
|
};
|
|
2404
2529
|
responses: {
|
|
2405
2530
|
/** @description The request is not valid */
|
|
@@ -5213,4 +5338,127 @@ export interface operations {
|
|
|
5213
5338
|
429: components["responses"]["E429"];
|
|
5214
5339
|
};
|
|
5215
5340
|
};
|
|
5341
|
+
listTranslationLocales: {
|
|
5342
|
+
parameters: {
|
|
5343
|
+
query?: never;
|
|
5344
|
+
header?: never;
|
|
5345
|
+
path: {
|
|
5346
|
+
/** @description The project's UUID. */
|
|
5347
|
+
uuid: string;
|
|
5348
|
+
};
|
|
5349
|
+
cookie?: never;
|
|
5350
|
+
};
|
|
5351
|
+
requestBody?: never;
|
|
5352
|
+
responses: {
|
|
5353
|
+
/** @description OK */
|
|
5354
|
+
200: {
|
|
5355
|
+
headers: {
|
|
5356
|
+
[name: string]: unknown;
|
|
5357
|
+
};
|
|
5358
|
+
content: {
|
|
5359
|
+
"application/json": components["schemas"]["TranslationLocales"];
|
|
5360
|
+
};
|
|
5361
|
+
};
|
|
5362
|
+
401: components["responses"]["E401"];
|
|
5363
|
+
403: components["responses"]["E403"];
|
|
5364
|
+
429: components["responses"]["E429"];
|
|
5365
|
+
};
|
|
5366
|
+
};
|
|
5367
|
+
getTranslations: {
|
|
5368
|
+
parameters: {
|
|
5369
|
+
query?: {
|
|
5370
|
+
/** @description i18next: only the texts (TranslationTexts), as i18next backends load them. */
|
|
5371
|
+
format?: "i18next";
|
|
5372
|
+
/** @description Dotted keys instead of nested objects. */
|
|
5373
|
+
flat?: "1" | "0" | "true" | "false";
|
|
5374
|
+
/** @description Default on: the default locale's text for keys not translated yet. 0: only this locale's own texts. */
|
|
5375
|
+
fallback?: "1" | "0" | "true" | "false";
|
|
5376
|
+
/** @description The current translations version: a long-cached address (a new version is a new address). */
|
|
5377
|
+
v?: number;
|
|
5378
|
+
};
|
|
5379
|
+
header?: never;
|
|
5380
|
+
path: {
|
|
5381
|
+
/** @description The project's UUID. */
|
|
5382
|
+
uuid: string;
|
|
5383
|
+
/** @description A locale of the project; "ar-SA" is answered by "ar" when the project has only "ar". */
|
|
5384
|
+
locale: string;
|
|
5385
|
+
};
|
|
5386
|
+
cookie?: never;
|
|
5387
|
+
};
|
|
5388
|
+
requestBody?: never;
|
|
5389
|
+
responses: {
|
|
5390
|
+
/** @description The bundle, or with format=i18next only its texts */
|
|
5391
|
+
200: {
|
|
5392
|
+
headers: {
|
|
5393
|
+
[name: string]: unknown;
|
|
5394
|
+
};
|
|
5395
|
+
content: {
|
|
5396
|
+
"application/json": components["schemas"]["TranslationBundle"] | components["schemas"]["TranslationTexts"];
|
|
5397
|
+
};
|
|
5398
|
+
};
|
|
5399
|
+
401: components["responses"]["E401"];
|
|
5400
|
+
403: components["responses"]["E403"];
|
|
5401
|
+
404: components["responses"]["E404"];
|
|
5402
|
+
429: components["responses"]["E429"];
|
|
5403
|
+
};
|
|
5404
|
+
};
|
|
5405
|
+
listTranslationLocalesByKey: {
|
|
5406
|
+
parameters: {
|
|
5407
|
+
query?: never;
|
|
5408
|
+
header?: never;
|
|
5409
|
+
path?: never;
|
|
5410
|
+
cookie?: never;
|
|
5411
|
+
};
|
|
5412
|
+
requestBody?: never;
|
|
5413
|
+
responses: {
|
|
5414
|
+
/** @description OK */
|
|
5415
|
+
200: {
|
|
5416
|
+
headers: {
|
|
5417
|
+
[name: string]: unknown;
|
|
5418
|
+
};
|
|
5419
|
+
content: {
|
|
5420
|
+
"application/json": components["schemas"]["TranslationLocales"];
|
|
5421
|
+
};
|
|
5422
|
+
};
|
|
5423
|
+
401: components["responses"]["E401"];
|
|
5424
|
+
403: components["responses"]["E403"];
|
|
5425
|
+
429: components["responses"]["E429"];
|
|
5426
|
+
};
|
|
5427
|
+
};
|
|
5428
|
+
getTranslationsByKey: {
|
|
5429
|
+
parameters: {
|
|
5430
|
+
query?: {
|
|
5431
|
+
/** @description i18next: only the texts (TranslationTexts), as i18next backends load them. */
|
|
5432
|
+
format?: "i18next";
|
|
5433
|
+
/** @description Dotted keys instead of nested objects. */
|
|
5434
|
+
flat?: "1" | "0" | "true" | "false";
|
|
5435
|
+
/** @description Default on: the default locale's text for keys not translated yet. 0: only this locale's own texts. */
|
|
5436
|
+
fallback?: "1" | "0" | "true" | "false";
|
|
5437
|
+
/** @description The current translations version: a long-cached address (a new version is a new address). */
|
|
5438
|
+
v?: number;
|
|
5439
|
+
};
|
|
5440
|
+
header?: never;
|
|
5441
|
+
path: {
|
|
5442
|
+
/** @description A locale of the project; "ar-SA" is answered by "ar" when the project has only "ar". */
|
|
5443
|
+
locale: string;
|
|
5444
|
+
};
|
|
5445
|
+
cookie?: never;
|
|
5446
|
+
};
|
|
5447
|
+
requestBody?: never;
|
|
5448
|
+
responses: {
|
|
5449
|
+
/** @description The bundle, or with format=i18next only its texts */
|
|
5450
|
+
200: {
|
|
5451
|
+
headers: {
|
|
5452
|
+
[name: string]: unknown;
|
|
5453
|
+
};
|
|
5454
|
+
content: {
|
|
5455
|
+
"application/json": components["schemas"]["TranslationBundle"] | components["schemas"]["TranslationTexts"];
|
|
5456
|
+
};
|
|
5457
|
+
};
|
|
5458
|
+
401: components["responses"]["E401"];
|
|
5459
|
+
403: components["responses"]["E403"];
|
|
5460
|
+
404: components["responses"]["E404"];
|
|
5461
|
+
429: components["responses"]["E429"];
|
|
5462
|
+
};
|
|
5463
|
+
};
|
|
5216
5464
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -19,6 +19,8 @@ export { ProcessesResource } from './processes.js';
|
|
|
19
19
|
export type { ProcessRun, ProcessRunDetail, ProcessRunListOptions } from './processes.js';
|
|
20
20
|
export { FormsResource } from './forms.js';
|
|
21
21
|
export type { FormDetail, FormResponse, FormResponseListOptions, FormResponsePage, FormSummary } from './forms.js';
|
|
22
|
+
export { TranslationsResource, fetchTranslations, fetchTranslationResource, fetchTranslationLocales, createTranslator, VeroxmI18nextBackend, } from './translations.js';
|
|
23
|
+
export type { FetchTranslationsOptions, TranslationBundle, TranslationBundleOptions, TranslationLocale, TranslationLocales, TranslationTexts, TranslationValues, Translator, VeroxmI18nextBackendOptions, } from './translations.js';
|
|
22
24
|
export { embedForm, embedFormsFromPage } from './embed.js';
|
|
23
25
|
export type { FormEmbed, FormEmbedMode, FormEmbedOpenTrigger, FormEmbedOptions, FormEmbedTracker } from './embed.js';
|
|
24
26
|
export type { Schemas } from './schemas.js';
|
package/dist/index.js
CHANGED
|
@@ -10,6 +10,8 @@ export { FunctionsResource } from './functions.js';
|
|
|
10
10
|
export { TasksResource } from './tasks.js';
|
|
11
11
|
export { ProcessesResource } from './processes.js';
|
|
12
12
|
export { FormsResource } from './forms.js';
|
|
13
|
+
// App translations: a locale's bundle in one request, and a t() for its texts.
|
|
14
|
+
export { TranslationsResource, fetchTranslations, fetchTranslationResource, fetchTranslationLocales, createTranslator, VeroxmI18nextBackend, } from './translations.js';
|
|
13
15
|
// Showing forms in a page: inline, popup, full page or toast.
|
|
14
16
|
export { embedForm, embedFormsFromPage } from './embed.js';
|
|
15
17
|
export { VeroXMApiError, VeroXMNotAuthenticatedError, VeroXMTimeoutError, VeroXMTwoStepRequiredError } from './errors.js';
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import type { VeroXMApp } from './client.js';
|
|
2
|
+
import { type RequestControl } from './http.js';
|
|
3
|
+
import type { Schemas } from './schemas.js';
|
|
4
|
+
/** Nested texts: `{ checkout: { pay: "Pay {{amount}}" } }`. With `flat`, dotted keys instead: `{ "checkout.pay": ... }`. */
|
|
5
|
+
export type TranslationTexts = Schemas['TranslationTexts'];
|
|
6
|
+
/** One locale of the project: its names, writing direction (`dir`, for `<html dir>`) and `translated` of `total` keys. */
|
|
7
|
+
export type TranslationLocale = Schemas['TranslationLocale'];
|
|
8
|
+
/** The project's locales, and the translations `version` (pass it as `version` for an address cached for a year). */
|
|
9
|
+
export type TranslationLocales = Schemas['TranslationLocales'];
|
|
10
|
+
/** A locale's whole bundle: its texts, direction, names, and `fallback` (keys shown in the default locale). */
|
|
11
|
+
export type TranslationBundle = Schemas['TranslationBundle'];
|
|
12
|
+
export interface TranslationBundleOptions extends RequestControl {
|
|
13
|
+
/** Fill keys this locale doesn't have yet from the default locale. Default: true. */
|
|
14
|
+
fallback?: boolean;
|
|
15
|
+
/** Dotted keys (`"checkout.pay"`) instead of nested objects. Default: false. */
|
|
16
|
+
flat?: boolean;
|
|
17
|
+
/** The project's translations version (from `locales()` or an earlier bundle): an address cached for a year. */
|
|
18
|
+
version?: number;
|
|
19
|
+
/** Extra attempts after a network error, a timeout, or 429, 502, 503 or 504. Default: the app's `retries`. */
|
|
20
|
+
retries?: number;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* The project's app translations, read with any of its keys (`auth.signInWithApiKey`), a browser key too. Bundles are
|
|
24
|
+
* cached by browsers and CDNs; pass `version` for an address that never changes.
|
|
25
|
+
*/
|
|
26
|
+
export declare class TranslationsResource {
|
|
27
|
+
private readonly app;
|
|
28
|
+
constructor(app: VeroXMApp);
|
|
29
|
+
/** The locales with their names, writing direction and coverage, and the current version. */
|
|
30
|
+
locales(options?: RequestControl & {
|
|
31
|
+
retries?: number;
|
|
32
|
+
}): Promise<TranslationLocales>;
|
|
33
|
+
/** A locale's bundle: its texts, direction and names. A locale the project doesn't have rejects with 404 `locale_not_found`. */
|
|
34
|
+
get(locale: string, options?: TranslationBundleOptions): Promise<TranslationBundle>;
|
|
35
|
+
/** Only the texts, as i18next loads a resource: `i18n.addResourceBundle('ar', 'translation', await app.translations.resource('ar'))`. */
|
|
36
|
+
resource(locale: string, options?: TranslationBundleOptions): Promise<TranslationTexts>;
|
|
37
|
+
}
|
|
38
|
+
export interface FetchTranslationsOptions extends TranslationBundleOptions {
|
|
39
|
+
/** Your VeroXM deployment's origin, e.g. "https://cms.example.com". */
|
|
40
|
+
baseUrl: string;
|
|
41
|
+
/** The project's UUID: its own address, which CDNs can cache. */
|
|
42
|
+
projectId: string;
|
|
43
|
+
/** Any key of the project (a browser key is enough): sent as `Authorization: Bearer <apiKey>`. */
|
|
44
|
+
apiKey: string;
|
|
45
|
+
/** The fetch to send with (e.g. one adding Next.js cache options). Default: the global fetch. */
|
|
46
|
+
fetch?: typeof fetch;
|
|
47
|
+
}
|
|
48
|
+
/** A locale's bundle without a VeroXMApp: `await fetchTranslations({ baseUrl, projectId, apiKey, locale: 'ar' })`. */
|
|
49
|
+
export declare function fetchTranslations(options: FetchTranslationsOptions & {
|
|
50
|
+
locale: string;
|
|
51
|
+
}): Promise<TranslationBundle>;
|
|
52
|
+
/** Only the texts, as i18next loads them, without a VeroXMApp. */
|
|
53
|
+
export declare function fetchTranslationResource(options: FetchTranslationsOptions & {
|
|
54
|
+
locale: string;
|
|
55
|
+
}): Promise<TranslationTexts>;
|
|
56
|
+
/** The project's locales without a VeroXMApp. */
|
|
57
|
+
export declare function fetchTranslationLocales(options: Omit<FetchTranslationsOptions, 'fallback' | 'flat' | 'version'>): Promise<TranslationLocales>;
|
|
58
|
+
/** Values for a text's `{{placeholders}}`; `count` also picks a plural form (`key_one`, `key_other`...). */
|
|
59
|
+
export type TranslationValues = Record<string, unknown> & {
|
|
60
|
+
count?: number;
|
|
61
|
+
};
|
|
62
|
+
export interface Translator {
|
|
63
|
+
/**
|
|
64
|
+
* The text for `key` with its `{{placeholders}}` filled in, i18next-style: `{{name}}`, `{{user.name}}`, `{{- html}}`
|
|
65
|
+
* and `{{price, currency}}` (the format part is ignored), `$t(other.key)` for another text, and plural forms by
|
|
66
|
+
* `count` (`cart.items_one`, `cart.items_other`). A key with no text gives the key itself, or `fallback`.
|
|
67
|
+
*/
|
|
68
|
+
(key: string, values?: TranslationValues, fallback?: string): string;
|
|
69
|
+
/** True when the bundle has a text for `key`. */
|
|
70
|
+
has(key: string): boolean;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* A `t(key, values)` over a bundle's texts (nested or flat), e.g. `createTranslator(bundle.translations, { locale:
|
|
74
|
+
* bundle.locale })`. The locale picks plural forms; without one, `count === 1` is "one" and anything else "other".
|
|
75
|
+
*/
|
|
76
|
+
export declare function createTranslator(texts: TranslationTexts, options?: {
|
|
77
|
+
locale?: string;
|
|
78
|
+
}): Translator;
|
|
79
|
+
export interface VeroxmI18nextBackendOptions extends Omit<FetchTranslationsOptions, 'flat' | 'signal'> {
|
|
80
|
+
/** The namespace that gets the whole bundle. Other namespaces get the texts under their name. Default: "translation". */
|
|
81
|
+
defaultNamespace?: string;
|
|
82
|
+
}
|
|
83
|
+
type ReadCallback = (error: unknown, data: TranslationTexts | false | null) => void;
|
|
84
|
+
/**
|
|
85
|
+
* An i18next backend that loads each language from VeroXM in one request:
|
|
86
|
+
*
|
|
87
|
+
* ```ts
|
|
88
|
+
* i18next.use(VeroxmI18nextBackend).init({
|
|
89
|
+
* lng: 'ar', fallbackLng: 'en',
|
|
90
|
+
* backend: { baseUrl: 'https://cms.example.com', projectId: '<project uuid>', apiKey: '<browser key>' },
|
|
91
|
+
* });
|
|
92
|
+
* ```
|
|
93
|
+
*
|
|
94
|
+
* The "translation" namespace gets the whole bundle; another namespace, such as `useTranslation('checkout')`, gets the
|
|
95
|
+
* texts under `checkout`. A language the project doesn't have loads as empty, so i18next falls back to `fallbackLng`.
|
|
96
|
+
*/
|
|
97
|
+
export declare class VeroxmI18nextBackend {
|
|
98
|
+
static readonly type: "backend";
|
|
99
|
+
readonly type: "backend";
|
|
100
|
+
private options;
|
|
101
|
+
private readonly loading;
|
|
102
|
+
constructor(services?: unknown, options?: VeroxmI18nextBackendOptions);
|
|
103
|
+
init(_services?: unknown, options?: VeroxmI18nextBackendOptions): void;
|
|
104
|
+
read(language: string, namespace: string, callback: ReadCallback): void;
|
|
105
|
+
}
|
|
106
|
+
export {};
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
import { rawRequest } from './http.js';
|
|
2
|
+
function bundleQuery(options, format) {
|
|
3
|
+
return {
|
|
4
|
+
format,
|
|
5
|
+
fallback: options.fallback === false ? 0 : undefined,
|
|
6
|
+
flat: options.flat ? 1 : undefined,
|
|
7
|
+
v: options.version,
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
function control(options) {
|
|
11
|
+
return { signal: options.signal, timeoutMs: options.timeoutMs, retries: options.retries };
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* The project's app translations, read with any of its keys (`auth.signInWithApiKey`), a browser key too. Bundles are
|
|
15
|
+
* cached by browsers and CDNs; pass `version` for an address that never changes.
|
|
16
|
+
*/
|
|
17
|
+
export class TranslationsResource {
|
|
18
|
+
constructor(app) {
|
|
19
|
+
this.app = app;
|
|
20
|
+
}
|
|
21
|
+
/** The locales with their names, writing direction and coverage, and the current version. */
|
|
22
|
+
async locales(options = {}) {
|
|
23
|
+
return (await this.app.request({ path: '/translations', ...control(options) }));
|
|
24
|
+
}
|
|
25
|
+
/** A locale's bundle: its texts, direction and names. A locale the project doesn't have rejects with 404 `locale_not_found`. */
|
|
26
|
+
async get(locale, options = {}) {
|
|
27
|
+
return (await this.app.request({ path: `/translations/${encodeURIComponent(locale)}`, query: bundleQuery(options), ...control(options) }));
|
|
28
|
+
}
|
|
29
|
+
/** Only the texts, as i18next loads a resource: `i18n.addResourceBundle('ar', 'translation', await app.translations.resource('ar'))`. */
|
|
30
|
+
async resource(locale, options = {}) {
|
|
31
|
+
return (await this.app.request({ path: `/translations/${encodeURIComponent(locale)}`, query: bundleQuery(options, 'i18next'), ...control(options) }));
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
function projectBase(options) {
|
|
35
|
+
return `${options.baseUrl.replace(/\/$/, '')}/public/v2/projects/${encodeURIComponent(options.projectId)}`;
|
|
36
|
+
}
|
|
37
|
+
function send(options, path, query) {
|
|
38
|
+
return rawRequest(projectBase(options), { path, query, headers: { Authorization: `Bearer ${options.apiKey}` }, ...control(options) }, { fetch: options.fetch });
|
|
39
|
+
}
|
|
40
|
+
/** A locale's bundle without a VeroXMApp: `await fetchTranslations({ baseUrl, projectId, apiKey, locale: 'ar' })`. */
|
|
41
|
+
export async function fetchTranslations(options) {
|
|
42
|
+
return (await send(options, `/translations/${encodeURIComponent(options.locale)}`, bundleQuery(options)));
|
|
43
|
+
}
|
|
44
|
+
/** Only the texts, as i18next loads them, without a VeroXMApp. */
|
|
45
|
+
export async function fetchTranslationResource(options) {
|
|
46
|
+
return (await send(options, `/translations/${encodeURIComponent(options.locale)}`, bundleQuery(options, 'i18next')));
|
|
47
|
+
}
|
|
48
|
+
/** The project's locales without a VeroXMApp. */
|
|
49
|
+
export async function fetchTranslationLocales(options) {
|
|
50
|
+
return (await send(options, '/translations'));
|
|
51
|
+
}
|
|
52
|
+
function lookup(texts, key) {
|
|
53
|
+
const direct = texts[key];
|
|
54
|
+
if (typeof direct === 'string')
|
|
55
|
+
return direct;
|
|
56
|
+
let node = texts;
|
|
57
|
+
for (const part of key.split('.')) {
|
|
58
|
+
if (!node || typeof node !== 'object')
|
|
59
|
+
return undefined;
|
|
60
|
+
node = node[part];
|
|
61
|
+
}
|
|
62
|
+
return typeof node === 'string' ? node : undefined;
|
|
63
|
+
}
|
|
64
|
+
function valueAt(values, path) {
|
|
65
|
+
if (path in values)
|
|
66
|
+
return values[path];
|
|
67
|
+
let node = values;
|
|
68
|
+
for (const part of path.split('.')) {
|
|
69
|
+
if (node === null || typeof node !== 'object')
|
|
70
|
+
return undefined;
|
|
71
|
+
node = node[part];
|
|
72
|
+
}
|
|
73
|
+
return node;
|
|
74
|
+
}
|
|
75
|
+
const PLACEHOLDER = /\{\{\s*(?:-\s*)?([^{},\s-][^{},\s]*)\s*(?:,[^{}]*)?\}\}/g;
|
|
76
|
+
const NESTED = /\$t\(\s*([^,()\s]+)\s*\)/g;
|
|
77
|
+
/**
|
|
78
|
+
* A `t(key, values)` over a bundle's texts (nested or flat), e.g. `createTranslator(bundle.translations, { locale:
|
|
79
|
+
* bundle.locale })`. The locale picks plural forms; without one, `count === 1` is "one" and anything else "other".
|
|
80
|
+
*/
|
|
81
|
+
export function createTranslator(texts, options = {}) {
|
|
82
|
+
let plurals;
|
|
83
|
+
try {
|
|
84
|
+
if (options.locale && typeof Intl !== 'undefined')
|
|
85
|
+
plurals = new Intl.PluralRules(options.locale);
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
plurals = undefined;
|
|
89
|
+
}
|
|
90
|
+
const form = (count) => (plurals ? plurals.select(count) : count === 1 ? 'one' : 'other');
|
|
91
|
+
const find = (key, values) => {
|
|
92
|
+
if (values && typeof values.count === 'number') {
|
|
93
|
+
const plural = (values.count === 0 ? lookup(texts, `${key}_zero`) : undefined) ?? lookup(texts, `${key}_${form(values.count)}`) ?? lookup(texts, `${key}_other`);
|
|
94
|
+
if (plural !== undefined)
|
|
95
|
+
return plural;
|
|
96
|
+
}
|
|
97
|
+
return lookup(texts, key);
|
|
98
|
+
};
|
|
99
|
+
const render = (text, values, depth) => {
|
|
100
|
+
let out = depth < 5 ? text.replace(NESTED, (whole, k) => {
|
|
101
|
+
const inner = find(k, values);
|
|
102
|
+
return inner === undefined ? whole : render(inner, values, depth + 1);
|
|
103
|
+
}) : text;
|
|
104
|
+
if (values) {
|
|
105
|
+
out = out.replace(PLACEHOLDER, (whole, name) => {
|
|
106
|
+
const v = valueAt(values, name);
|
|
107
|
+
return v === undefined || v === null ? whole : String(v);
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
return out;
|
|
111
|
+
};
|
|
112
|
+
const t = ((key, values, fallback) => {
|
|
113
|
+
const text = find(key, values);
|
|
114
|
+
if (text === undefined)
|
|
115
|
+
return fallback ?? key;
|
|
116
|
+
return render(text, values, 0);
|
|
117
|
+
});
|
|
118
|
+
t.has = (key) => lookup(texts, key) !== undefined;
|
|
119
|
+
return t;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* An i18next backend that loads each language from VeroXM in one request:
|
|
123
|
+
*
|
|
124
|
+
* ```ts
|
|
125
|
+
* i18next.use(VeroxmI18nextBackend).init({
|
|
126
|
+
* lng: 'ar', fallbackLng: 'en',
|
|
127
|
+
* backend: { baseUrl: 'https://cms.example.com', projectId: '<project uuid>', apiKey: '<browser key>' },
|
|
128
|
+
* });
|
|
129
|
+
* ```
|
|
130
|
+
*
|
|
131
|
+
* The "translation" namespace gets the whole bundle; another namespace, such as `useTranslation('checkout')`, gets the
|
|
132
|
+
* texts under `checkout`. A language the project doesn't have loads as empty, so i18next falls back to `fallbackLng`.
|
|
133
|
+
*/
|
|
134
|
+
export class VeroxmI18nextBackend {
|
|
135
|
+
constructor(services, options) {
|
|
136
|
+
this.type = 'backend';
|
|
137
|
+
this.loading = new Map();
|
|
138
|
+
this.init(services, options);
|
|
139
|
+
}
|
|
140
|
+
init(_services, options) {
|
|
141
|
+
if (options)
|
|
142
|
+
this.options = options;
|
|
143
|
+
}
|
|
144
|
+
read(language, namespace, callback) {
|
|
145
|
+
const options = this.options;
|
|
146
|
+
if (!options?.baseUrl || !options.projectId || !options.apiKey) {
|
|
147
|
+
callback(new Error('VeroxmI18nextBackend needs backend: { baseUrl, projectId, apiKey }.'), false);
|
|
148
|
+
return;
|
|
149
|
+
}
|
|
150
|
+
if (language === 'cimode') {
|
|
151
|
+
callback(null, {});
|
|
152
|
+
return;
|
|
153
|
+
}
|
|
154
|
+
// One request per language, whatever the number of namespaces.
|
|
155
|
+
let texts = this.loading.get(language);
|
|
156
|
+
if (!texts) {
|
|
157
|
+
texts = fetchTranslationResource({ ...options, locale: language }).catch((e) => {
|
|
158
|
+
this.loading.delete(language);
|
|
159
|
+
if (isMissingLocale(e))
|
|
160
|
+
return {};
|
|
161
|
+
throw e;
|
|
162
|
+
});
|
|
163
|
+
this.loading.set(language, texts);
|
|
164
|
+
}
|
|
165
|
+
texts.then((all) => {
|
|
166
|
+
if (namespace === (options.defaultNamespace ?? 'translation'))
|
|
167
|
+
return callback(null, all);
|
|
168
|
+
const part = all[namespace];
|
|
169
|
+
callback(null, part && typeof part === 'object' ? part : {});
|
|
170
|
+
}, (e) => callback(e, false));
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
VeroxmI18nextBackend.type = 'backend';
|
|
174
|
+
function isMissingLocale(e) {
|
|
175
|
+
const err = e;
|
|
176
|
+
return !!err && err.status === 404 && err.code === 'locale_not_found';
|
|
177
|
+
}
|