Skip to content

Documenting the new client-customizable locale detection system #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Documenting the new client-customizable locale detection system #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 12 additions & 4 deletions src/extending-components/with-i18n-reactive.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ The following methods are available within the component on `this..i18n`.
The `t()` method retrieves the translation message for the current locale.
The following arguments can be passed to the `t()` method.

| Argument | Type | Required | Description |
| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | Yes | The key for the specific message. This can be a nested key like `buttons.increment` |
| `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' }` |
Expand All @@ -67,9 +67,17 @@ The `setLocale()` method sets the current locale of the i18n instance.

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

| Argument | Type | Required | Description |
|----------|----------|----------|----------------------------------------|
| `locale` | `string` | Yes | The locale string. The default is `en` |
| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `locale` | `string` | Yes | The locale string. The default is `en` |

## detectLocale(callback)

The `detectLocale(callback)` method triggers the automated locale detection procedure and updates the current locale accordingly.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `callback` | `function` | | A function that is called after locale detection has completed. It is invoked with two arguments: `oldLocale` and `newLocale` |

## setI18n method

Expand Down
12 changes: 10 additions & 2 deletions src/extending-components/with-i18n.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ The following methods are available within the component on `this..i18n`.
The `t()` method retrieves the translation message for the current locale.
The following arguments can be passed to the `t()` method.

| Argument | Type | Required | Description |
| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | Yes | The key for the specific message. This can be a nested key like `buttons.increment` |
| `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' }` |
Expand All @@ -57,10 +57,18 @@ The `setLocale()` method sets the current locale of the i18n instance.

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

| Argument | Type | Required | Description |
| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `locale` | `string` | Yes | The locale string. The default is `en` |

## detectLocale(callback)

The `detectLocale(callback)` method triggers the automated locale detection procedure and updates the current locale accordingly.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `callback` | `function` | | A function that is called after locale detection has completed. It is invoked with two arguments: `oldLocale` and `newLocale` |

## setI18n method

The `setI18n()` method can be called when an instance needs to be set after the component has initialised.
Expand Down
62 changes: 56 additions & 6 deletions src/i18n/create-i18n.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ import { createI18n } from 'https://cdn.skypack.dev/ficusjs@6'
const i18n = createI18n()
```

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

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

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

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

| Argument | Type | Required | Description |
| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | `string` | Yes | The key for the specific message. This can be a nested key like `navbar.buttons.home` |
| `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' }` |
Expand All @@ -108,11 +108,11 @@ i18n.t('greeting', { name: 'FicusJS' }, { locale: 'es' })

### setLocale(locale)

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

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

| Argument | Type | Required | Description |
| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `locale` | `string` | Yes | The locale string. The default is `en` |

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

## detectLocale(callback)

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.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `callback` | `function` | | A function that is called after locale detection has completed. It is invoked with two arguments: `newLocale` and `oldLocale` |

```js
import { getEventBus } from 'https://cdn.skypack.dev/ficusjs@6'

// Notify reactive components when the current locale is updated
i18n.detectLocale((newLocale, oldLocale) => {
if (newLocale !== oldLocale) {
getEventBus().publish('i18n:locale:changed', newLocale)
}
})
````

### interpolateWith(userRE)

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

### setLocaleDetectionRule(rule)

the `setLocaleDetectionRule()` method updates the user-defined locale detection rule.

| Argument | Type | Required | Description |
| --- | --- | --- | --- |
| `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 |

- 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;
- 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;
- 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.

```js
// Disable user-defined locale detection and instead rely on the fallback detection methods
I18n.setLocaleDetectionRule(null)

// Force user-defined locale detection to 'fr'
I18n.setLocaleDetectionRule('fr')

// Get locale from subdomain, if present in the URL, relying on the fallback detection methods if undefined
I18n.setLocaleDetectionRule(() =>
new URL(window.location).host.split('.').reverse()[2]
)

// Asynchronously query a back-end API, relying on the fallback detection methods in case of HTTP error or undefined result
I18n.setLocaleDetectionRule(() =>
fetch('https/example.com/user/123?setting=locale')
.then(resp => { if (resp.ok) return resp.text() })
)
```

### setPluralizationRule(locale, rule, options)

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

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

```js
Expand Down