Skip to content

Commit 86a0e05

Browse files
mesrmesr
committed
Documented the new customizable locale detection feature:
 - Updated description of the locale detection procedure at the top of page `i18n/create-i18n.md`; - Added section `detectLocale(callback)` to pages `extending-components/with-i18n.md` and `extending-components/with-18n-reactive.md`; - Added sections `setLocaleDetectionRule(rule)` and `detectLocale(callback)` to page `i18n/create-i18n.md`.
1 parent d028853 commit 86a0e05

File tree

3 files changed

+78
-12
lines changed

3 files changed

+78
-12
lines changed

‎src/extending-components/with-i18n-reactive.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ The following methods are available within the component on `this..i18n`.
5151
The `t()` method retrieves the translation message for the current locale.
5252
The following arguments can be passed to the `t()` method.
5353

54-
| Argument | Type | Required | Description |
54+
| Argument | Type | Required | Description |
5555
| --- | --- | --- | --- |
5656
| `key` | `string` | Yes | The key for the specific message. This can be a nested key like `buttons.increment` |
5757
| `templateData` | `object` | | The optional data for message interpolation. The keys must match the message value. For example; the message `Greeting {{ name }}` requires a `templateData` object containing `{ name: 'FicuJS' }` |
@@ -67,9 +67,17 @@ The `setLocale()` method sets the current locale of the i18n instance.
6767

6868
The following arguments can be passed to the `setLocale()` method.
6969

70-
| Argument | Type | Required | Description |
71-
|----------|----------|----------|----------------------------------------|
72-
| `locale` | `string` | Yes | The locale string. The default is `en` |
70+
| Argument | Type | Required | Description |
71+
| --- | --- | --- | --- |
72+
| `locale` | `string` | Yes | The locale string. The default is `en` |
73+
74+
## detectLocale(callback)
75+
76+
The `detectLocale(callback)` method triggers the automated locale detection procedure and updates the current locale accordingly.
77+
78+
| Argument | Type | Required | Description |
79+
| --- | --- | --- | --- |
80+
| `callback` | `function` | | A function that is called after locale detection has completed. It is invoked with two arguments: `oldLocale` and `newLocale` |
7381

7482
## setI18n method
7583

‎src/extending-components/with-i18n.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ The following methods are available within the component on `this..i18n`.
4141
The `t()` method retrieves the translation message for the current locale.
4242
The following arguments can be passed to the `t()` method.
4343

44-
| Argument | Type | Required | Description |
44+
| Argument | Type | Required | Description |
4545
| --- | --- | --- | --- |
4646
| `key` | `string` | Yes | The key for the specific message. This can be a nested key like `buttons.increment` |
4747
| `templateData` | `object` | | The optional data for message interpolation. The keys must match the message value. For example; the message `Greeting {{ name }}` requires a `templateData` object containing `{ name: 'FicuJS' }` |
@@ -57,10 +57,18 @@ The `setLocale()` method sets the current locale of the i18n instance.
5757

5858
The following arguments can be passed to the `setLocale()` method.
5959

60-
| Argument | Type | Required | Description |
60+
| Argument | Type | Required | Description |
6161
| --- | --- | --- | --- |
6262
| `locale` | `string` | Yes | The locale string. The default is `en` |
6363

64+
## detectLocale(callback)
65+
66+
The `detectLocale(callback)` method triggers the automated locale detection procedure and updates the current locale accordingly.
67+
68+
| Argument | Type | Required | Description |
69+
| --- | --- | --- | --- |
70+
| `callback` | `function` | | A function that is called after locale detection has completed. It is invoked with two arguments: `oldLocale` and `newLocale` |
71+
6472
## setI18n method
6573

6674
The `setI18n()` method can be called when an instance needs to be set after the component has initialised.

‎src/i18n/create-i18n.md‎

Lines changed: 56 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,9 @@ import { createI18n } from 'https://cdn.skypack.dev/ficusjs@6'
1616
const i18n = createI18n()
1717
```
1818

19-
The current locale is set according to the following rules:
19+
Upon instantiation, the current locale is automatically detected according to the following rules:
2020

21-
1. `lang` query string parameter `?lang=es`
21+
1. User-defined detection function (defaults to a function that reads the value of the `lang` query-string parameter, e.g. `?lang=es`)
2222
2. HTML `lang` attribute `<html lang="es">`
2323
3. `navigator.language` property
2424

@@ -89,7 +89,7 @@ i18n.t('itemsCaption', { num: 2 }, { pluralizeTo: 'num' }) // outputs "2 items"
8989

9090
The following arguments can be passed to the `t()` method.
9191

92-
| Argument | Type | Required | Description |
92+
| Argument | Type | Required | Description |
9393
| --- | --- | --- | --- |
9494
| `key` | `string` | Yes | The key for the specific message. This can be a nested key like `navbar.buttons.home` |
9595
| `templateData` | `object` | | The optional data for message interpolation. The keys must match the message value. For example; the message <code>Greeting {\{ name }}</code> requires a `templateData` object containing `{ name: 'FicusJS' }` |
@@ -108,11 +108,11 @@ i18n.t('greeting', { name: 'FicusJS' }, { locale: 'es' })
108108

109109
### setLocale(locale)
110110

111-
The `setLocale()` method sets the current locale of the i18n instance.
111+
The `setLocale()` method sets the current locale of the i18n instance without triggering automatic locale detection.
112112

113113
The following arguments can be passed to the `setLocale()` method.
114114

115-
| Argument | Type | Required | Description |
115+
| Argument | Type | Required | Description |
116116
| --- | --- | --- | --- |
117117
| `locale` | `string` | Yes | The locale string. The default is `en` |
118118

@@ -130,6 +130,25 @@ const locale = i18n.getLocale()
130130
// locale is 'es'
131131
```
132132

133+
## detectLocale(callback)
134+
135+
The `detectLocale()` method triggers the automated locale detection procedure and updates the current locale accordingly. If no detection methods provide a value, the current locale stays unchanged.
136+
137+
| Argument | Type | Required | Description |
138+
| --- | --- | --- | --- |
139+
| `callback` | `function` | | A function that is called after locale detection has completed. It is invoked with two arguments: `newLocale` and `oldLocale` |
140+
141+
```js
142+
import { getEventBus } from 'https://cdn.skypack.dev/ficusjs@6'
143+
144+
// Notify reactive components when the current locale is updated
145+
i18n.detectLocale((newLocale, oldLocale) => {
146+
if (newLocale !== oldLocale) {
147+
getEventBus().publish('i18n:locale:changed', newLocale)
148+
}
149+
})
150+
````
151+
133152
### interpolateWith(userRE)
134153

135154
The `interpolateWith()` method sets the regular expression for template strings interpolation.
@@ -151,14 +170,45 @@ const value = i18n.t('welcomeMessage', { userName: 'George' })
151170
// value is 'Hello George'
152171
```
153172

173+
### setLocaleDetectionRule(rule)
174+
175+
the `setLocaleDetectionRule()` method updates the user-defined locale detection rule.
176+
177+
| Argument | Type | Required | Description |
178+
| --- | --- | --- | --- |
179+
| `rule` | any | | Either a static value, a promise that resolves to a static value, or a function that returns either a static value or a promise that resolves to a static value |
180+
181+
- If `rule` is a function, it is re-evaluated every time that the locale detection procedure is triggered, and its result is treated according to the following two rules;
182+
- If `rule` or the result of a `rule` function is a string or a promise that resolves to a string, the current locale is set to that value;
183+
- If `rule` or the result of a `rule` function is a non-string value or a promise that resolves to a non-string value, the locale detection procedure skips the user-defined detection rule.
184+
185+
```js
186+
// Disable user-defined locale detection and instead rely on the fallback detection methods
187+
I18n.setLocaleDetectionRule(null)
188+
189+
// Force user-defined locale detection to 'fr'
190+
I18n.setLocaleDetectionRule('fr')
191+
192+
// Get locale from subdomain, if present in the URL, relying on the fallback detection methods if undefined
193+
I18n.setLocaleDetectionRule(() =>
194+
new URL(window.location).host.split('.').reverse()[2]
195+
)
196+
197+
// Asynchronously query a back-end API, relying on the fallback detection methods in case of HTTP error or undefined result
198+
I18n.setLocaleDetectionRule(() =>
199+
fetch('https/example.com/user/123?setting=locale')
200+
.then(resp => { if (resp.ok) return resp.text() })
201+
)
202+
```
203+
154204
### setPluralizationRule(locale, rule, options)
155205

156206
The `setPluralizationRule()` method sets a locale-specific pluralization rule function to determine plural form variation index.
157207

158208
| Argument | Type | Required | Description |
159209
| --- | --- | --- | --- |
160210
| `locale` | `string` | Yes | The locale that the `rule` function is defined for |
161-
| `rule` | `function` | Yes | A locale-specific function that receive a count as parameter and returns an index into the array of pluralized translated messages |
211+
| `rule` | `function` | Yes | A locale-specific function that receives a count as parameter and returns an index into the array of pluralized translated messages |
162212
| `options` | `object` | | An optional set of locale-specific options for the pluralization rule |
163213

164214
```js

0 commit comments

Comments
 (0)