@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 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 replaces them when it loads more.
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. Replaces `translations` with the supplied map. Namespaces left out of the map are dropped; an omitted `translations` field keeps the current map. |
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 replaces the map instead of merging into it. `ITranslationsServiceDefinition` is now `ITranslationsDefinition`.
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 { Menu: { moreButtonLabel: 'More' } }
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
- * Looks up a translated string by key within one namespace.
20
+ * Retrieves a translated string by its key, from the namespace passed to `translate()`.
19
21
  *
20
- * Returns the translation when there is one. Otherwise returns `fallback` when supplied, and `key` when not.
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
- (key: string): string | undefined;
24
- (key: string, fallback: string): string;
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
- /** Looks up translated strings by namespace and key. */
37
+ /** Retrieves translated strings for your component's text, by namespace and key. */
27
38
  export interface ITranslationsService {
28
39
  /**
29
- * Returns a lookup function for the strings in `namespace`.
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
- * Translations can change while the page is open. Call the lookup function while a component renders,
32
- * so the component updates when they change.
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
- * Returns every translated string in `namespace`, keyed by key.
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
- * Returns an empty object when the namespace has no translations. Don't change the returned object; it's
39
- * the service's own copy.
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. Replaces config values when the host's state changes. */
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;AAkDzD,4EAA4E;AAC/D,QAAA,sBAAsB,GAAG,IAAA,oCAAa,EAClD,gCAAgC,CAChC,CAAA"}
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(translations);
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;YAChC,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC,CACD,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 { Menu: { moreButtonLabel: 'More' } }
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
- * Looks up a translated string by key within one namespace.
20
+ * Retrieves a translated string by its key, from the namespace passed to `translate()`.
19
21
  *
20
- * Returns the translation when there is one. Otherwise returns `fallback` when supplied, and `key` when not.
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
- (key: string): string | undefined;
24
- (key: string, fallback: string): string;
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
- /** Looks up translated strings by namespace and key. */
37
+ /** Retrieves translated strings for your component's text, by namespace and key. */
27
38
  export interface ITranslationsService {
28
39
  /**
29
- * Returns a lookup function for the strings in `namespace`.
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
- * Translations can change while the page is open. Call the lookup function while a component renders,
32
- * so the component updates when they change.
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
- * Returns every translated string in `namespace`, keyed by key.
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
- * Returns an empty object when the namespace has no translations. Don't change the returned object; it's
39
- * the service's own copy.
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. Replaces config values when the host's state changes. */
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;AAkDzD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAClD,gCAAgC,CAChC,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(translations);
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;YAChC,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC,CACD,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.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": "5b840925c7af67e8564e7a3da33610c2865567d8a8391553b4f9ae18"
80
+ "falconPackageHash": "8c5712d43dbee87d5aaef206d41c56e74beba99e4742f481e188ddf4"
81
81
  }
@@ -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 { Menu: { moreButtonLabel: 'More' } }
7
+ * @exampleValue `{ "ProductGallery": { "emptyStateMessage": "No products to show yet" } }`
8
8
  */
9
- export type Translations = { [namespace: string]: { [key: string]: string } }
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
- * Looks up a translated string by key within one namespace.
24
+ * Retrieves a translated string by its key, from the namespace passed to `translate()`.
19
25
  *
20
- * Returns the translation when there is one. Otherwise returns `fallback` when supplied, and `key` when not.
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
- (key: string): string | undefined
24
- (key: string, fallback: string): string
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
- /** Looks up translated strings by namespace and key. */
42
+ /** Retrieves translated strings for your component's text, by namespace and key. */
28
43
  export interface ITranslationsService {
29
44
  /**
30
- * Returns a lookup function for the strings in `namespace`.
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
- * Translations can change while the page is open. Call the lookup function while a component renders,
33
- * so the component updates when they change.
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
- * Returns every translated string in `namespace`, keyed by key.
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
- * Returns an empty object when the namespace has no translations. Don't change the returned object; it's
41
- * the service's own copy.
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. Replaces config values when the host's state changes. */
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(translations)
24
+ _translations.set({
25
+ ..._translations.get(),
26
+ ...translations,
27
+ })
25
28
  }
26
29
  },
27
30
  }