svelte-i18n/docs/Formatting.md

177 lines
5.4 KiB
Markdown
Raw Normal View History

2020-02-03 17:38:22 +01:00
<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->
<!-- code_chunk_output -->
- [Message syntax](#message-syntax)
- [`$format` or `$_` or `$t`](#format-or-_-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)
- [Formats](#formats)
- [Accessing formatters directly](#accessing-formatters-directly)
<!-- /code_chunk_output -->
2020-01-16 03:06:42 +01:00
### 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/guides/basic-i18n/)
- [Runtime Environments](https://formatjs.io/guides/runtime-environments/)
- [ICU Message Syntax](https://formatjs.io/guides/message-syntax/)
### `$format` or `$_` 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
<script>
import { _ } from 'svelte-i18n'
</script>
<h1>{$_('page_title')}</h1>
```
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<string, string | number | Date>
}
```
- `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.
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
<div>{$_('shallow.prop')}</div> <!-- Shallow property -->
<div>{$_('deep.prop')}</div> <!-- Deep property -->
```
2020-01-21 14:11:10 +01:00
### `$time(number: Date, options: MessageObject)`
2020-01-16 03:06:42 +01:00
2020-01-21 14:11:10 +01:00
`import { time } from 'svelte-i18n'`
2020-01-16 03:06:42 +01:00
Formats a date object into a time string with the specified format. Please refer to the [#formats](#formats) section to see available formats.
```html
2020-01-21 14:11:10 +01:00
<div>{$time(new Date(2019, 3, 24, 23, 45))}</div>
2020-01-16 03:06:42 +01:00
<!-- 11:45 PM -->
2020-01-21 14:11:10 +01:00
<div>{$time(new Date(2019, 3, 24, 23, 45), { format: 'medium' } )}</div>
2020-01-16 03:06:42 +01:00
<!-- 11:45:00 PM -->
```
2020-02-03 17:38:22 +01:00
### `$date(date: Date, options: MessageObject)`
2020-01-21 14:11:10 +01:00
`import { date } from 'svelte-i18n'`
2020-01-16 03:06:42 +01:00
Formats a date object into a string with the specified format. Please refer to the [#formats](#formats) section to see available formats.
```html
2020-01-21 14:11:10 +01:00
<div>{$date(new Date(2019, 3, 24, 23, 45))}</div>
2020-01-16 03:06:42 +01:00
<!-- 4/24/19 -->
2020-01-21 14:11:10 +01:00
<div>{$date(new Date(2019, 3, 24, 23, 45), { format: 'medium' } )}</div>
2020-01-16 03:06:42 +01:00
<!-- Apr 24, 2019 -->
```
2020-02-03 17:38:22 +01:00
### `$number(number: number, options: MessageObject)`
2020-01-21 14:11:10 +01:00
`import { number } from 'svelte-i18n'`
2020-01-16 03:06:42 +01:00
Formats a number with the specified locale and format. Please refer to the [#formats](#formats) section to see available formats.
```html
2020-01-21 14:11:10 +01:00
<div>{$number(100000000)}</div>
2020-01-16 03:06:42 +01:00
<!-- 100,000,000 -->
2020-01-21 14:11:10 +01:00
<div>{$number(100000000, { locale: 'pt' })}</div>
2020-01-16 03:06:42 +01:00
<!-- 100.000.000 -->
```
### 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.