@wix/site-service-translations 1.0.0 → 1.0.2
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 +3 -3
- package/cjs/build/definition/index.d.ts +108 -13
- package/cjs/build/definition/index.js.map +1 -1
- package/cjs/build/implementations/translationsService.js +4 -1
- package/cjs/build/implementations/translationsService.js.map +1 -1
- package/dist/definition/index.d.ts +108 -13
- package/dist/definition/index.js.map +1 -1
- package/dist/implementations/translationsService.js +4 -1
- package/dist/implementations/translationsService.js.map +1 -1
- package/package.json +2 -2
- package/src/definition/index.ts +113 -14
- package/src/implementations/translationsService.ts +4 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @wix/site-service-translations
|
|
2
2
|
|
|
3
|
-
Looks up translated strings by namespace and key. The host (Thunderbolt) supplies the translations and
|
|
3
|
+
Looks up translated strings by namespace and key. The host (Thunderbolt) supplies the translations and merges in more namespaces when it loads them.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -31,7 +31,7 @@ Declare `'@wix/site-service-translations'` in your component's `serviceDependenc
|
|
|
31
31
|
|---|---|---|---|
|
|
32
32
|
| `translate` | `(namespace: string) => TranslateByKey` | never | Returns a lookup function for one namespace. The lookup returns the translation, else `fallback` when supplied, else `key`. An empty-string `fallback` is returned as is. |
|
|
33
33
|
| `getTranslations` | `(namespace: string) => { [key: string]: string }` | never | Returns every string in one namespace. Returns `{}` when the namespace has no translations. |
|
|
34
|
-
| `_updateConfig` | `(Partial<ITranslationsServiceConfig>) => void` | never | Host-only.
|
|
34
|
+
| `_updateConfig` | `(Partial<ITranslationsServiceConfig>) => void` | never | Host-only. Merges the supplied map into `translations` by namespace: each supplied namespace replaces the current one, and namespaces left out are kept. An omitted `translations` field keeps the current map. |
|
|
35
35
|
|
|
36
36
|
```ts
|
|
37
37
|
interface TranslateByKey {
|
|
@@ -62,4 +62,4 @@ Translations are signal-backed through `@wix/services-definitions/core-services/
|
|
|
62
62
|
|
|
63
63
|
`translate` and `getTranslations` are unchanged. Change the import path from `@wix/viewer-service-translations` to `@wix/site-service-translations`, and the service dependency from `'@wix/viewer-service-translations'` to `'@wix/site-service-translations'`.
|
|
64
64
|
|
|
65
|
-
Hosts only: `onConfigChange(config)` is now `_updateConfig(config)`, and it
|
|
65
|
+
Hosts only: `onConfigChange(config)` is now `_updateConfig(config)`, and it still merges by namespace. `ITranslationsServiceDefinition` is now `ITranslationsDefinition`.
|
|
@@ -2,10 +2,12 @@ import type { ServiceDefinition } from '@wix/services-definitions';
|
|
|
2
2
|
/**
|
|
3
3
|
* Translated strings, grouped by namespace and then by key.
|
|
4
4
|
*
|
|
5
|
-
* @exampleValue {
|
|
5
|
+
* @exampleValue `{ "ProductGallery": { "emptyStateMessage": "No products to show yet" } }`
|
|
6
6
|
*/
|
|
7
7
|
export type Translations = {
|
|
8
|
+
/** Translated strings in a namespace. */
|
|
8
9
|
[namespace: string]: {
|
|
10
|
+
/** Translated string. The key is the string's name in its namespace. */
|
|
9
11
|
[key: string]: string;
|
|
10
12
|
};
|
|
11
13
|
};
|
|
@@ -15,33 +17,126 @@ export type ITranslationsServiceConfig = {
|
|
|
15
17
|
translations: Translations;
|
|
16
18
|
};
|
|
17
19
|
/**
|
|
18
|
-
*
|
|
20
|
+
* Retrieves a translated string by its key, from the namespace passed to `translate()`.
|
|
19
21
|
*
|
|
20
|
-
* Returns the
|
|
22
|
+
* Returns the translated string. When the namespace has no string for the key, returns `fallback` when you
|
|
23
|
+
* specify one, and the key itself when you don't.
|
|
21
24
|
*/
|
|
22
25
|
export interface TranslateByKey {
|
|
23
|
-
|
|
24
|
-
|
|
26
|
+
/**
|
|
27
|
+
* Retrieves a translated string by its key. When the namespace has no string for `key`, it returns the key
|
|
28
|
+
* itself, unless you specify a fallback.
|
|
29
|
+
*
|
|
30
|
+
* @param key Key of the string. Case-sensitive, and must match the key exactly.
|
|
31
|
+
* @param fallback String to return when the namespace has no string for `key`. An empty-string fallback is
|
|
32
|
+
* returned as is.
|
|
33
|
+
* @returns Translated string.
|
|
34
|
+
*/
|
|
35
|
+
(key: string, fallback?: string): string;
|
|
25
36
|
}
|
|
26
|
-
/**
|
|
37
|
+
/** Retrieves translated strings for your component's text, by namespace and key. */
|
|
27
38
|
export interface ITranslationsService {
|
|
28
39
|
/**
|
|
29
|
-
*
|
|
40
|
+
* Retrieves a lookup function for the translated strings in a namespace.
|
|
41
|
+
*
|
|
42
|
+
* Call the lookup function with a key to retrieve that key's string. When the namespace has no string for
|
|
43
|
+
* the key, it returns the fallback you specify, or the key itself when you don't specify one. A string
|
|
44
|
+
* that's empty in the namespace is returned as is, not replaced by the fallback.
|
|
45
|
+
*
|
|
46
|
+
* To show your own default text when there's no string, specify it as the fallback, as in
|
|
47
|
+
* `t('nextButtonAriaLabel', 'Next product')`. Without a fallback, the lookup function returns the key, so a
|
|
48
|
+
* default you add with `??` or `||`, as in `t('nextButtonAriaLabel') ?? 'Next product'`, isn't used for a missing
|
|
49
|
+
* string.
|
|
50
|
+
*
|
|
51
|
+
* The lookup function reads the current strings each time you call it, so a lookup function you keep
|
|
52
|
+
* returns the current strings, even after they change. Call it while a component renders, so the component
|
|
53
|
+
* updates when the strings change.
|
|
54
|
+
*
|
|
55
|
+
* To retrieve every string in a namespace at once, use `getTranslations()`.
|
|
56
|
+
*
|
|
57
|
+
* @param namespace Namespace of the strings. Case-sensitive, and must match the namespace exactly.
|
|
58
|
+
* @returns Function that retrieves a translated string by its key. When the namespace has no string for the
|
|
59
|
+
* key, it returns the key itself, unless you specify a fallback.
|
|
60
|
+
*
|
|
61
|
+
* @exampleValue namespace 'ProductGallery'
|
|
62
|
+
*
|
|
63
|
+
* @example Label a button for screen readers
|
|
64
|
+
* ```tsx
|
|
65
|
+
* import { useService } from '@wix/services-manager-react'
|
|
66
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
67
|
+
*
|
|
68
|
+
* function NextProductButton({ onClick }: { onClick: () => void }) {
|
|
69
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
70
|
+
* const t = translationsService.translate('ProductGallery')
|
|
30
71
|
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
72
|
+
* return (
|
|
73
|
+
* <button aria-label={t('nextButtonAriaLabel', 'Next product')} onClick={onClick}>
|
|
74
|
+
* →
|
|
75
|
+
* </button>
|
|
76
|
+
* )
|
|
77
|
+
* }
|
|
78
|
+
* ```
|
|
79
|
+
*
|
|
80
|
+
* @example Show a validation error
|
|
81
|
+
* ```tsx
|
|
82
|
+
* import { useService } from '@wix/services-manager-react'
|
|
83
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
84
|
+
*
|
|
85
|
+
* function PhoneError({ isValid }: { isValid: boolean }) {
|
|
86
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
87
|
+
* const t = translationsService.translate('ContactForm')
|
|
88
|
+
*
|
|
89
|
+
* return isValid ? null : <p role="alert">{t('invalidPhoneError', 'Enter a valid phone number')}</p>
|
|
90
|
+
* }
|
|
91
|
+
* ```
|
|
33
92
|
*/
|
|
34
93
|
translate: (namespace: string) => TranslateByKey;
|
|
35
94
|
/**
|
|
36
|
-
*
|
|
95
|
+
* Retrieves every translated string in a namespace.
|
|
96
|
+
*
|
|
97
|
+
* Use it when you need several strings at once, such as to pass a set of labels to your own code. To
|
|
98
|
+
* retrieve a single string with a fallback, use `translate()`.
|
|
99
|
+
*
|
|
100
|
+
* The strings can change while the page is open. Call it while a component renders, so the component
|
|
101
|
+
* updates when they change.
|
|
102
|
+
*
|
|
103
|
+
* Don't change the returned map. Every component on the page reads the same map, so a change shows in all
|
|
104
|
+
* of them, and the site doesn't save it.
|
|
105
|
+
*
|
|
106
|
+
* @param namespace Namespace of the strings. Case-sensitive, and must match the namespace exactly.
|
|
107
|
+
* @returns Translated strings in the namespace.
|
|
108
|
+
*
|
|
109
|
+
* An empty map when the namespace has no strings.
|
|
110
|
+
*
|
|
111
|
+
* @exampleValue namespace 'ProductGallery'
|
|
112
|
+
* @exampleValue `{ "emptyStateMessage": "No products to show yet", "nextButtonAriaLabel": "Next product" }`
|
|
113
|
+
*
|
|
114
|
+
* @example Pass a component's labels to your own code
|
|
115
|
+
* ```tsx
|
|
116
|
+
* import { useService } from '@wix/services-manager-react'
|
|
117
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
118
|
+
*
|
|
119
|
+
* // Carousel is your own component, and Product is your own type.
|
|
120
|
+
* function ProductCarousel({ products }: { products: Product[] }) {
|
|
121
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
122
|
+
* const strings = translationsService.getTranslations('ProductGallery')
|
|
37
123
|
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
124
|
+
* // getTranslations() has no fallback, so a missing key is undefined.
|
|
125
|
+
* return (
|
|
126
|
+
* <Carousel
|
|
127
|
+
* items={products}
|
|
128
|
+
* nextLabel={strings.nextButtonAriaLabel ?? 'Next product'}
|
|
129
|
+
* previousLabel={strings.previousButtonAriaLabel ?? 'Previous product'}
|
|
130
|
+
* />
|
|
131
|
+
* )
|
|
132
|
+
* }
|
|
133
|
+
* ```
|
|
40
134
|
*/
|
|
41
135
|
getTranslations: (namespace: string) => Translations[string];
|
|
42
|
-
/** @internal Host-only.
|
|
136
|
+
/** @internal Host-only. Merges the supplied translations in by namespace; namespaces left out are kept. */
|
|
43
137
|
_updateConfig: (config: Partial<ITranslationsServiceConfig>) => void;
|
|
44
138
|
}
|
|
139
|
+
/** Definition of the Translations service, used to resolve it from the services manager. */
|
|
45
140
|
export type ITranslationsDefinition = ServiceDefinition<ITranslationsService, ITranslationsServiceConfig>;
|
|
46
141
|
/** Definition of the Translations service. Specify it in `useService()`. */
|
|
47
142
|
export declare const TranslationsDefinition: string & {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/definition/index.ts"],"names":[],"mappings":";;;AAAA,oEAAyD;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/definition/index.ts"],"names":[],"mappings":";;;AAAA,oEAAyD;AAqJzD,4EAA4E;AAC/D,QAAA,sBAAsB,GAAG,IAAA,oCAAa,EAClD,gCAAgC,CAChC,CAAA"}
|
|
@@ -17,7 +17,10 @@ exports.TranslationsService = (0, services_definitions_1.implementService)(defin
|
|
|
17
17
|
},
|
|
18
18
|
_updateConfig({ translations }) {
|
|
19
19
|
if (translations) {
|
|
20
|
-
_translations.set(
|
|
20
|
+
_translations.set({
|
|
21
|
+
..._translations.get(),
|
|
22
|
+
...translations,
|
|
23
|
+
});
|
|
21
24
|
}
|
|
22
25
|
},
|
|
23
26
|
};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"translationsService.js","sourceRoot":"","sources":["../../../src/implementations/translationsService.ts"],"names":[],"mappings":";;;AAAA,oEAA4D;AAE5D,6EAA0F;AAE1F,8CAAsD;AAEzC,QAAA,mBAAmB,GAAG,IAAA,uCAAgB,EAClD,mCAAsB,EACtB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAkD,EAAwB,EAAE;IAChG,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,kCAAwB,CAAC,CAAA;IACvD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IAEjD,OAAO;QACN,SAAS,CAAC,SAAS;YAClB,MAAM,cAAc,GAAG,CAAC,GAAW,EAAE,QAAiB,EAAE,EAAE,CACzD,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,QAAQ,IAAI,GAAG,CAAA;YACzD,OAAO,cAAgC,CAAA;QACxC,CAAC;QACD,eAAe,CAAC,SAAS;YACxB,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;QAC5C,CAAC;QACD,aAAa,CAAC,EAAE,YAAY,EAAuC;YAClE,IAAI,YAAY,EAAE,CAAC;gBAClB,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;
|
|
1
|
+
{"version":3,"file":"translationsService.js","sourceRoot":"","sources":["../../../src/implementations/translationsService.ts"],"names":[],"mappings":";;;AAAA,oEAA4D;AAE5D,6EAA0F;AAE1F,8CAAsD;AAEzC,QAAA,mBAAmB,GAAG,IAAA,uCAAgB,EAClD,mCAAsB,EACtB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAkD,EAAwB,EAAE;IAChG,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,kCAAwB,CAAC,CAAA;IACvD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IAEjD,OAAO;QACN,SAAS,CAAC,SAAS;YAClB,MAAM,cAAc,GAAG,CAAC,GAAW,EAAE,QAAiB,EAAE,EAAE,CACzD,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,QAAQ,IAAI,GAAG,CAAA;YACzD,OAAO,cAAgC,CAAA;QACxC,CAAC;QACD,eAAe,CAAC,SAAS;YACxB,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;QAC5C,CAAC;QACD,aAAa,CAAC,EAAE,YAAY,EAAuC;YAClE,IAAI,YAAY,EAAE,CAAC;gBAClB,aAAa,CAAC,GAAG,CAAC;oBACjB,GAAG,aAAa,CAAC,GAAG,EAAE;oBACtB,GAAG,YAAY;iBACf,CAAC,CAAA;YACH,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC,CACD,CAAA"}
|
|
@@ -2,10 +2,12 @@ import type { ServiceDefinition } from '@wix/services-definitions';
|
|
|
2
2
|
/**
|
|
3
3
|
* Translated strings, grouped by namespace and then by key.
|
|
4
4
|
*
|
|
5
|
-
* @exampleValue {
|
|
5
|
+
* @exampleValue `{ "ProductGallery": { "emptyStateMessage": "No products to show yet" } }`
|
|
6
6
|
*/
|
|
7
7
|
export type Translations = {
|
|
8
|
+
/** Translated strings in a namespace. */
|
|
8
9
|
[namespace: string]: {
|
|
10
|
+
/** Translated string. The key is the string's name in its namespace. */
|
|
9
11
|
[key: string]: string;
|
|
10
12
|
};
|
|
11
13
|
};
|
|
@@ -15,33 +17,126 @@ export type ITranslationsServiceConfig = {
|
|
|
15
17
|
translations: Translations;
|
|
16
18
|
};
|
|
17
19
|
/**
|
|
18
|
-
*
|
|
20
|
+
* Retrieves a translated string by its key, from the namespace passed to `translate()`.
|
|
19
21
|
*
|
|
20
|
-
* Returns the
|
|
22
|
+
* Returns the translated string. When the namespace has no string for the key, returns `fallback` when you
|
|
23
|
+
* specify one, and the key itself when you don't.
|
|
21
24
|
*/
|
|
22
25
|
export interface TranslateByKey {
|
|
23
|
-
|
|
24
|
-
|
|
26
|
+
/**
|
|
27
|
+
* Retrieves a translated string by its key. When the namespace has no string for `key`, it returns the key
|
|
28
|
+
* itself, unless you specify a fallback.
|
|
29
|
+
*
|
|
30
|
+
* @param key Key of the string. Case-sensitive, and must match the key exactly.
|
|
31
|
+
* @param fallback String to return when the namespace has no string for `key`. An empty-string fallback is
|
|
32
|
+
* returned as is.
|
|
33
|
+
* @returns Translated string.
|
|
34
|
+
*/
|
|
35
|
+
(key: string, fallback?: string): string;
|
|
25
36
|
}
|
|
26
|
-
/**
|
|
37
|
+
/** Retrieves translated strings for your component's text, by namespace and key. */
|
|
27
38
|
export interface ITranslationsService {
|
|
28
39
|
/**
|
|
29
|
-
*
|
|
40
|
+
* Retrieves a lookup function for the translated strings in a namespace.
|
|
41
|
+
*
|
|
42
|
+
* Call the lookup function with a key to retrieve that key's string. When the namespace has no string for
|
|
43
|
+
* the key, it returns the fallback you specify, or the key itself when you don't specify one. A string
|
|
44
|
+
* that's empty in the namespace is returned as is, not replaced by the fallback.
|
|
45
|
+
*
|
|
46
|
+
* To show your own default text when there's no string, specify it as the fallback, as in
|
|
47
|
+
* `t('nextButtonAriaLabel', 'Next product')`. Without a fallback, the lookup function returns the key, so a
|
|
48
|
+
* default you add with `??` or `||`, as in `t('nextButtonAriaLabel') ?? 'Next product'`, isn't used for a missing
|
|
49
|
+
* string.
|
|
50
|
+
*
|
|
51
|
+
* The lookup function reads the current strings each time you call it, so a lookup function you keep
|
|
52
|
+
* returns the current strings, even after they change. Call it while a component renders, so the component
|
|
53
|
+
* updates when the strings change.
|
|
54
|
+
*
|
|
55
|
+
* To retrieve every string in a namespace at once, use `getTranslations()`.
|
|
56
|
+
*
|
|
57
|
+
* @param namespace Namespace of the strings. Case-sensitive, and must match the namespace exactly.
|
|
58
|
+
* @returns Function that retrieves a translated string by its key. When the namespace has no string for the
|
|
59
|
+
* key, it returns the key itself, unless you specify a fallback.
|
|
60
|
+
*
|
|
61
|
+
* @exampleValue namespace 'ProductGallery'
|
|
62
|
+
*
|
|
63
|
+
* @example Label a button for screen readers
|
|
64
|
+
* ```tsx
|
|
65
|
+
* import { useService } from '@wix/services-manager-react'
|
|
66
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
67
|
+
*
|
|
68
|
+
* function NextProductButton({ onClick }: { onClick: () => void }) {
|
|
69
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
70
|
+
* const t = translationsService.translate('ProductGallery')
|
|
30
71
|
*
|
|
31
|
-
*
|
|
32
|
-
*
|
|
72
|
+
* return (
|
|
73
|
+
* <button aria-label={t('nextButtonAriaLabel', 'Next product')} onClick={onClick}>
|
|
74
|
+
* →
|
|
75
|
+
* </button>
|
|
76
|
+
* )
|
|
77
|
+
* }
|
|
78
|
+
* ```
|
|
79
|
+
*
|
|
80
|
+
* @example Show a validation error
|
|
81
|
+
* ```tsx
|
|
82
|
+
* import { useService } from '@wix/services-manager-react'
|
|
83
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
84
|
+
*
|
|
85
|
+
* function PhoneError({ isValid }: { isValid: boolean }) {
|
|
86
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
87
|
+
* const t = translationsService.translate('ContactForm')
|
|
88
|
+
*
|
|
89
|
+
* return isValid ? null : <p role="alert">{t('invalidPhoneError', 'Enter a valid phone number')}</p>
|
|
90
|
+
* }
|
|
91
|
+
* ```
|
|
33
92
|
*/
|
|
34
93
|
translate: (namespace: string) => TranslateByKey;
|
|
35
94
|
/**
|
|
36
|
-
*
|
|
95
|
+
* Retrieves every translated string in a namespace.
|
|
96
|
+
*
|
|
97
|
+
* Use it when you need several strings at once, such as to pass a set of labels to your own code. To
|
|
98
|
+
* retrieve a single string with a fallback, use `translate()`.
|
|
99
|
+
*
|
|
100
|
+
* The strings can change while the page is open. Call it while a component renders, so the component
|
|
101
|
+
* updates when they change.
|
|
102
|
+
*
|
|
103
|
+
* Don't change the returned map. Every component on the page reads the same map, so a change shows in all
|
|
104
|
+
* of them, and the site doesn't save it.
|
|
105
|
+
*
|
|
106
|
+
* @param namespace Namespace of the strings. Case-sensitive, and must match the namespace exactly.
|
|
107
|
+
* @returns Translated strings in the namespace.
|
|
108
|
+
*
|
|
109
|
+
* An empty map when the namespace has no strings.
|
|
110
|
+
*
|
|
111
|
+
* @exampleValue namespace 'ProductGallery'
|
|
112
|
+
* @exampleValue `{ "emptyStateMessage": "No products to show yet", "nextButtonAriaLabel": "Next product" }`
|
|
113
|
+
*
|
|
114
|
+
* @example Pass a component's labels to your own code
|
|
115
|
+
* ```tsx
|
|
116
|
+
* import { useService } from '@wix/services-manager-react'
|
|
117
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
118
|
+
*
|
|
119
|
+
* // Carousel is your own component, and Product is your own type.
|
|
120
|
+
* function ProductCarousel({ products }: { products: Product[] }) {
|
|
121
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
122
|
+
* const strings = translationsService.getTranslations('ProductGallery')
|
|
37
123
|
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
124
|
+
* // getTranslations() has no fallback, so a missing key is undefined.
|
|
125
|
+
* return (
|
|
126
|
+
* <Carousel
|
|
127
|
+
* items={products}
|
|
128
|
+
* nextLabel={strings.nextButtonAriaLabel ?? 'Next product'}
|
|
129
|
+
* previousLabel={strings.previousButtonAriaLabel ?? 'Previous product'}
|
|
130
|
+
* />
|
|
131
|
+
* )
|
|
132
|
+
* }
|
|
133
|
+
* ```
|
|
40
134
|
*/
|
|
41
135
|
getTranslations: (namespace: string) => Translations[string];
|
|
42
|
-
/** @internal Host-only.
|
|
136
|
+
/** @internal Host-only. Merges the supplied translations in by namespace; namespaces left out are kept. */
|
|
43
137
|
_updateConfig: (config: Partial<ITranslationsServiceConfig>) => void;
|
|
44
138
|
}
|
|
139
|
+
/** Definition of the Translations service, used to resolve it from the services manager. */
|
|
45
140
|
export type ITranslationsDefinition = ServiceDefinition<ITranslationsService, ITranslationsServiceConfig>;
|
|
46
141
|
/** Definition of the Translations service. Specify it in `useService()`. */
|
|
47
142
|
export declare const TranslationsDefinition: string & {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAqJzD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAClD,gCAAgC,CAChC,CAAA"}
|
|
@@ -14,7 +14,10 @@ export const TranslationsService = implementService(TranslationsDefinition, ({ c
|
|
|
14
14
|
},
|
|
15
15
|
_updateConfig({ translations }) {
|
|
16
16
|
if (translations) {
|
|
17
|
-
_translations.set(
|
|
17
|
+
_translations.set({
|
|
18
|
+
..._translations.get(),
|
|
19
|
+
...translations,
|
|
20
|
+
});
|
|
18
21
|
}
|
|
19
22
|
},
|
|
20
23
|
};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"translationsService.js","sourceRoot":"","sources":["../../src/implementations/translationsService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAE5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iDAAiD,CAAA;AAE1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAEtD,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAClD,sBAAsB,EACtB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAkD,EAAwB,EAAE;IAChG,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,wBAAwB,CAAC,CAAA;IACvD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IAEjD,OAAO;QACN,SAAS,CAAC,SAAS;YAClB,MAAM,cAAc,GAAG,CAAC,GAAW,EAAE,QAAiB,EAAE,EAAE,CACzD,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,QAAQ,IAAI,GAAG,CAAA;YACzD,OAAO,cAAgC,CAAA;QACxC,CAAC;QACD,eAAe,CAAC,SAAS;YACxB,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;QAC5C,CAAC;QACD,aAAa,CAAC,EAAE,YAAY,EAAuC;YAClE,IAAI,YAAY,EAAE,CAAC;gBAClB,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;
|
|
1
|
+
{"version":3,"file":"translationsService.js","sourceRoot":"","sources":["../../src/implementations/translationsService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAE5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,iDAAiD,CAAA;AAE1F,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAEtD,MAAM,CAAC,MAAM,mBAAmB,GAAG,gBAAgB,CAClD,sBAAsB,EACtB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAkD,EAAwB,EAAE;IAChG,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,wBAAwB,CAAC,CAAA;IACvD,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IAEjD,OAAO;QACN,SAAS,CAAC,SAAS;YAClB,MAAM,cAAc,GAAG,CAAC,GAAW,EAAE,QAAiB,EAAE,EAAE,CACzD,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,QAAQ,IAAI,GAAG,CAAA;YACzD,OAAO,cAAgC,CAAA;QACxC,CAAC;QACD,eAAe,CAAC,SAAS;YACxB,OAAO,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,CAAA;QAC5C,CAAC;QACD,aAAa,CAAC,EAAE,YAAY,EAAuC;YAClE,IAAI,YAAY,EAAE,CAAC;gBAClB,aAAa,CAAC,GAAG,CAAC;oBACjB,GAAG,aAAa,CAAC,GAAG,EAAE;oBACtB,GAAG,YAAY;iBACf,CAAC,CAAA;YACH,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC,CACD,CAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wix/site-service-translations",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.2",
|
|
4
4
|
"license": "UNLICENSED",
|
|
5
5
|
"files": [
|
|
6
6
|
"dist",
|
|
@@ -77,5 +77,5 @@
|
|
|
77
77
|
]
|
|
78
78
|
}
|
|
79
79
|
},
|
|
80
|
-
"falconPackageHash": "
|
|
80
|
+
"falconPackageHash": "8c5712d43dbee87d5aaef206d41c56e74beba99e4742f481e188ddf4"
|
|
81
81
|
}
|
package/src/definition/index.ts
CHANGED
|
@@ -4,9 +4,15 @@ import type { ServiceDefinition } from '@wix/services-definitions'
|
|
|
4
4
|
/**
|
|
5
5
|
* Translated strings, grouped by namespace and then by key.
|
|
6
6
|
*
|
|
7
|
-
* @exampleValue {
|
|
7
|
+
* @exampleValue `{ "ProductGallery": { "emptyStateMessage": "No products to show yet" } }`
|
|
8
8
|
*/
|
|
9
|
-
export type Translations = {
|
|
9
|
+
export type Translations = {
|
|
10
|
+
/** Translated strings in a namespace. */
|
|
11
|
+
[namespace: string]: {
|
|
12
|
+
/** Translated string. The key is the string's name in its namespace. */
|
|
13
|
+
[key: string]: string
|
|
14
|
+
}
|
|
15
|
+
}
|
|
10
16
|
|
|
11
17
|
/** Values the host supplies when it creates the service. */
|
|
12
18
|
export type ITranslationsServiceConfig = {
|
|
@@ -15,37 +21,130 @@ export type ITranslationsServiceConfig = {
|
|
|
15
21
|
}
|
|
16
22
|
|
|
17
23
|
/**
|
|
18
|
-
*
|
|
24
|
+
* Retrieves a translated string by its key, from the namespace passed to `translate()`.
|
|
19
25
|
*
|
|
20
|
-
* Returns the
|
|
26
|
+
* Returns the translated string. When the namespace has no string for the key, returns `fallback` when you
|
|
27
|
+
* specify one, and the key itself when you don't.
|
|
21
28
|
*/
|
|
22
29
|
export interface TranslateByKey {
|
|
23
|
-
|
|
24
|
-
|
|
30
|
+
/**
|
|
31
|
+
* Retrieves a translated string by its key. When the namespace has no string for `key`, it returns the key
|
|
32
|
+
* itself, unless you specify a fallback.
|
|
33
|
+
*
|
|
34
|
+
* @param key Key of the string. Case-sensitive, and must match the key exactly.
|
|
35
|
+
* @param fallback String to return when the namespace has no string for `key`. An empty-string fallback is
|
|
36
|
+
* returned as is.
|
|
37
|
+
* @returns Translated string.
|
|
38
|
+
*/
|
|
39
|
+
(key: string, fallback?: string): string
|
|
25
40
|
}
|
|
26
41
|
|
|
27
|
-
/**
|
|
42
|
+
/** Retrieves translated strings for your component's text, by namespace and key. */
|
|
28
43
|
export interface ITranslationsService {
|
|
29
44
|
/**
|
|
30
|
-
*
|
|
45
|
+
* Retrieves a lookup function for the translated strings in a namespace.
|
|
46
|
+
*
|
|
47
|
+
* Call the lookup function with a key to retrieve that key's string. When the namespace has no string for
|
|
48
|
+
* the key, it returns the fallback you specify, or the key itself when you don't specify one. A string
|
|
49
|
+
* that's empty in the namespace is returned as is, not replaced by the fallback.
|
|
50
|
+
*
|
|
51
|
+
* To show your own default text when there's no string, specify it as the fallback, as in
|
|
52
|
+
* `t('nextButtonAriaLabel', 'Next product')`. Without a fallback, the lookup function returns the key, so a
|
|
53
|
+
* default you add with `??` or `||`, as in `t('nextButtonAriaLabel') ?? 'Next product'`, isn't used for a missing
|
|
54
|
+
* string.
|
|
55
|
+
*
|
|
56
|
+
* The lookup function reads the current strings each time you call it, so a lookup function you keep
|
|
57
|
+
* returns the current strings, even after they change. Call it while a component renders, so the component
|
|
58
|
+
* updates when the strings change.
|
|
59
|
+
*
|
|
60
|
+
* To retrieve every string in a namespace at once, use `getTranslations()`.
|
|
61
|
+
*
|
|
62
|
+
* @param namespace Namespace of the strings. Case-sensitive, and must match the namespace exactly.
|
|
63
|
+
* @returns Function that retrieves a translated string by its key. When the namespace has no string for the
|
|
64
|
+
* key, it returns the key itself, unless you specify a fallback.
|
|
65
|
+
*
|
|
66
|
+
* @exampleValue namespace 'ProductGallery'
|
|
67
|
+
*
|
|
68
|
+
* @example Label a button for screen readers
|
|
69
|
+
* ```tsx
|
|
70
|
+
* import { useService } from '@wix/services-manager-react'
|
|
71
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
72
|
+
*
|
|
73
|
+
* function NextProductButton({ onClick }: { onClick: () => void }) {
|
|
74
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
75
|
+
* const t = translationsService.translate('ProductGallery')
|
|
31
76
|
*
|
|
32
|
-
*
|
|
33
|
-
*
|
|
77
|
+
* return (
|
|
78
|
+
* <button aria-label={t('nextButtonAriaLabel', 'Next product')} onClick={onClick}>
|
|
79
|
+
* →
|
|
80
|
+
* </button>
|
|
81
|
+
* )
|
|
82
|
+
* }
|
|
83
|
+
* ```
|
|
84
|
+
*
|
|
85
|
+
* @example Show a validation error
|
|
86
|
+
* ```tsx
|
|
87
|
+
* import { useService } from '@wix/services-manager-react'
|
|
88
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
89
|
+
*
|
|
90
|
+
* function PhoneError({ isValid }: { isValid: boolean }) {
|
|
91
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
92
|
+
* const t = translationsService.translate('ContactForm')
|
|
93
|
+
*
|
|
94
|
+
* return isValid ? null : <p role="alert">{t('invalidPhoneError', 'Enter a valid phone number')}</p>
|
|
95
|
+
* }
|
|
96
|
+
* ```
|
|
34
97
|
*/
|
|
35
98
|
translate: (namespace: string) => TranslateByKey
|
|
36
99
|
|
|
37
100
|
/**
|
|
38
|
-
*
|
|
101
|
+
* Retrieves every translated string in a namespace.
|
|
102
|
+
*
|
|
103
|
+
* Use it when you need several strings at once, such as to pass a set of labels to your own code. To
|
|
104
|
+
* retrieve a single string with a fallback, use `translate()`.
|
|
105
|
+
*
|
|
106
|
+
* The strings can change while the page is open. Call it while a component renders, so the component
|
|
107
|
+
* updates when they change.
|
|
108
|
+
*
|
|
109
|
+
* Don't change the returned map. Every component on the page reads the same map, so a change shows in all
|
|
110
|
+
* of them, and the site doesn't save it.
|
|
111
|
+
*
|
|
112
|
+
* @param namespace Namespace of the strings. Case-sensitive, and must match the namespace exactly.
|
|
113
|
+
* @returns Translated strings in the namespace.
|
|
114
|
+
*
|
|
115
|
+
* An empty map when the namespace has no strings.
|
|
116
|
+
*
|
|
117
|
+
* @exampleValue namespace 'ProductGallery'
|
|
118
|
+
* @exampleValue `{ "emptyStateMessage": "No products to show yet", "nextButtonAriaLabel": "Next product" }`
|
|
119
|
+
*
|
|
120
|
+
* @example Pass a component's labels to your own code
|
|
121
|
+
* ```tsx
|
|
122
|
+
* import { useService } from '@wix/services-manager-react'
|
|
123
|
+
* import { TranslationsDefinition } from '@wix/site-service-translations/definition'
|
|
124
|
+
*
|
|
125
|
+
* // Carousel is your own component, and Product is your own type.
|
|
126
|
+
* function ProductCarousel({ products }: { products: Product[] }) {
|
|
127
|
+
* const translationsService = useService(TranslationsDefinition)
|
|
128
|
+
* const strings = translationsService.getTranslations('ProductGallery')
|
|
39
129
|
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
130
|
+
* // getTranslations() has no fallback, so a missing key is undefined.
|
|
131
|
+
* return (
|
|
132
|
+
* <Carousel
|
|
133
|
+
* items={products}
|
|
134
|
+
* nextLabel={strings.nextButtonAriaLabel ?? 'Next product'}
|
|
135
|
+
* previousLabel={strings.previousButtonAriaLabel ?? 'Previous product'}
|
|
136
|
+
* />
|
|
137
|
+
* )
|
|
138
|
+
* }
|
|
139
|
+
* ```
|
|
42
140
|
*/
|
|
43
141
|
getTranslations: (namespace: string) => Translations[string]
|
|
44
142
|
|
|
45
|
-
/** @internal Host-only.
|
|
143
|
+
/** @internal Host-only. Merges the supplied translations in by namespace; namespaces left out are kept. */
|
|
46
144
|
_updateConfig: (config: Partial<ITranslationsServiceConfig>) => void
|
|
47
145
|
}
|
|
48
146
|
|
|
147
|
+
/** Definition of the Translations service, used to resolve it from the services manager. */
|
|
49
148
|
export type ITranslationsDefinition = ServiceDefinition<ITranslationsService, ITranslationsServiceConfig>
|
|
50
149
|
|
|
51
150
|
/** Definition of the Translations service. Specify it in `useService()`. */
|
|
@@ -21,7 +21,10 @@ export const TranslationsService = implementService(
|
|
|
21
21
|
},
|
|
22
22
|
_updateConfig({ translations }: Partial<ITranslationsServiceConfig>) {
|
|
23
23
|
if (translations) {
|
|
24
|
-
_translations.set(
|
|
24
|
+
_translations.set({
|
|
25
|
+
..._translations.get(),
|
|
26
|
+
...translations,
|
|
27
|
+
})
|
|
25
28
|
}
|
|
26
29
|
},
|
|
27
30
|
}
|