- [Message syntax](#message-syntax) - [`$format`, `$_` or `$t`](#format-_-or-t) - [`$time(number: Date, options: MessageObject)`](#timenumber-date-options-messageobject) - [`$date(date: Date, options: MessageObject)`](#datedate-date-options-messageobject) - [`$number(number: number, options: MessageObject)`](#numbernumber-number-options-messageobject) - [`$json(messageId: string)`](#jsonmessageid-string) - [Formats](#formats) - [Accessing formatters directly](#accessing-formatters-directly) ### Message syntax Under the hood, `formatjs` is used for localizing your messages. It allows `svelte-i18n` to support the ICU message syntax. It is strongly recommended to read their documentation about it. - [Basic Internationalization Principles](https://formatjs.io/docs/core-concepts/basic-internationalization-principles) - [Runtime Environments](https://formatjs.io/docs/guides/runtime-requirements/) - [ICU Message Syntax](https://formatjs.io/docs/core-concepts/icu-syntax/) ### `$format`, `$_` or `$t` `import { _, t, format } from 'svelte-i18n'` The `$format` store is the actual formatter method. It's also aliased as `$_` and `$t` for convenience. To format a message is as simple as executing the `$format` method: ```svelte

{$_('page_title')}

``` The formatter can be called with two different signatures: - `format(messageId: string, options?: MessageObject): string` - `format(options: MessageObject): string` ```ts interface MessageObject { id?: string; locale?: string; format?: string; default?: string; values?: Record; } ``` - `id`: represents the path to a specific message; - `locale`: forces a specific locale; - `default`: the default value in case of message not found in the current locale; - `format`: the format to be used. See [#formats](#formats); - `values`: properties that should be interpolated in the message; You can pass a `string` as the first parameter for a less verbose way of formatting a message. It is also possible to inject values into the translation like so: ```jsonc // en.json { "awesome": "{name} is awesome!" } ``` ```svelte

{$_("awesome", { values: { name: "svelte-i18n" } })}

``` If the message id literal value is not in the root of the dicitonary, `.` (dots) are interpreted as a path: ```jsonc // en.json { "shallow.prop": "Shallow property", "deep": { "property": "Deep property" } } ``` ```svelte
{$_('shallow.prop')}
{$_('deep.property')}
``` ### `$time(number: Date, options: MessageObject)` `import { time } from 'svelte-i18n'` Formats a date object into a time string with the specified format. Please refer to the [#formats](#formats) section to see available formats. ```html
{$time(new Date(2019, 3, 24, 23, 45))}
{$time(new Date(2019, 3, 24, 23, 45), { format: 'medium' } )}
``` ### `$date(date: Date, options: MessageObject)` `import { date } from 'svelte-i18n'` Formats a date object into a string with the specified format. Please refer to the [#formats](#formats) section to see available formats. ```html
{$date(new Date(2019, 3, 24, 23, 45))}
{$date(new Date(2019, 3, 24, 23, 45), { format: 'medium' } )}
``` ### `$number(number: number, options: MessageObject)` `import { number } from 'svelte-i18n'` Formats a number with the specified locale and format. Please refer to the [#formats](#formats) section to see available formats. ```html
{$number(100000000)}
{$number(100000000, { locale: 'pt' })}
``` ### `$json(messageId: string)` `import { json } from 'svelte-i18n'` Returns the raw JSON value of the specified `messageId` for the current locale. While [`$format`](#format-_-or-t) always returns a string, `$json` can be used to get an object relative to the current locale. ```html ``` ### Formats `svelte-i18n` comes with a default set of `number`, `time` and `date` formats: **Number:** - `currency`: `{ style: 'currency' }` - `percent`: `{ style: 'percent' }` - `scientific`: `{ notation: 'scientific' }` - `engineering`: `{ notation: 'engineering' }` - `compactLong`: `{ notation: 'compact', compactDisplay: 'long' }` - `compactShort`: `{ notation: 'compact', compactDisplay: 'short' }` **Date:** - `short`: `{ month: 'numeric', day: 'numeric', year: '2-digit' }` - `medium`: `{ month: 'short', day: 'numeric', year: 'numeric' }` - `long`: `{ month: 'long', day: 'numeric', year: 'numeric' }` - `full`: `{ weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' }` **Time:** - `short`: `{ hour: 'numeric', minute: 'numeric' }` - `medium`: `{ hour: 'numeric', minute: 'numeric', second: 'numeric' }` - `long`: `{ hour: 'numeric', minute: 'numeric', second: 'numeric', timeZoneName: 'short' }` - `full`: `{ hour: 'numeric', minute: 'numeric', second: 'numeric', timeZoneName: 'short' }` ### Accessing formatters directly `svelte-i18n` also provides a low-level API to access its formatter methods: ```js import { getDateFormatter, getNumberFormatter, getTimeFormatter, getMessageFormatter, } from 'svelte-i18n'; ``` By using these methods, it's possible to manipulate values in a more specific way that fits your needs. For example, it's possible to create a method which receives a `date` and returns its relevant date related parts: ```js import { getDateFormatter } from 'svelte-i18n'; const getDateParts = (date) => getDateFormatter() .formatToParts(date) .filter(({ type }) => type !== 'literal') .reduce((acc, { type, value }) => { acc[type] = value; return acc; }, {}); getDateParts(new Date(2020, 0, 1)); // { month: '1', day: '1', year: '2020' } ``` Check the [methods documentation](/docs/Methods.md#low-level-api) for more information.