Add new documentation to readme

This commit is contained in:
Christian Kaisermann 2019-05-18 22:30:17 -03:00
parent 06072e0a9d
commit 2ebeac4ff0
7 changed files with 297 additions and 268 deletions

280
README.md
View File

@ -4,132 +4,224 @@
## Usage
### On the `store`
`svelte-i18n` utilizes svelte `stores` for keeping track of the current locale, dictionary of messages and the main format function. This way, we keep everything neat, in sync and easy to use on your svelte files.
---
### Locale
The `locale` store defines what is the current locale.
```js
import { i18n } from 'svelte-i18n'
import { Store } from 'svelte/store'
import { locale, dictionary } from 'svelte-i18n'
/** i18n(svelteStore, { dictionary }) */
let store = new Store()
// Set the current locale to en-US
locale.set('en-US')
store = i18n(store, {
dictionary: {
'pt-BR': {
message: 'Mensagem',
greeting: 'Olá {name}, como vai?',
greetingIndex: 'Olá {0}, como vai?',
meter: 'metros | metro | metros',
book: 'livro | livros',
messages: {
alert: 'Alerta',
error: 'Erro',
},
// This is a store, so we can subscribe to its changes
locale.subscribe(() => {
console.log('locale change')
})
```
---
### The dictionary
The `dictionary` store defines the dictionary of messages of all locales.
```js
import { locale, dictionary } from 'svelte-i18n'
// Define a locale dictionary
dictionary.set({
pt: {
message: 'Mensagem',
'switch.lang': 'Trocar idioma',
greeting: {
ask: 'Por favor, digite seu nome',
message: 'Olá {name}, como vai?',
},
'en-US': {
message: 'Message',
greeting: 'Hello {name}, how are you?',
greetingIndex: 'Hello {0}, how are you?',
meter: 'meters | meter | meters',
book: 'book | books',
messages: {
alert: 'Alert',
error: 'Error',
},
photos:
'Você {n, plural, =0 {não tem fotos.} =1 {tem uma foto.} other {tem # fotos.}}',
cats: 'Tenho {n, number} {n,plural,=0{gatos}one{gato}other{gatos}}',
},
en: {
message: 'Message',
'switch.lang': 'Switch language',
greeting: {
ask: 'Please type your name',
message: 'Hello {name}, how are you?',
},
photos:
'You have {n, plural, =0 {no photos.} =1 {one photo.} other {# photos.}}',
cats: 'I have {n, number} {n,plural,one{cat}other{cats}}',
},
})
/**
* Extend the initial dictionary.
* Dictionaries are deeply merged.
* */
store.i18n.extendDictionary({
'pt-BR': {
messages: {
warn: 'Aviso',
success: 'Sucesso',
},
},
'en-US': {
messages: {
warn: 'Warn',
success: 'Success',
},
},
// It's also possible to merge the current dictionary
// with other objets
dictionary.update(dict => {
dict.fr = {
// ...french messages
}
return dict
})
/** Set the initial locale */
store.i18n.setLocale('en-US')
```
### On `templates`
Each language message dictionary can be as deep as you want. Messages can also be looked up by a string represetation of it's path on the dictionary (i.e `greeting.message`).
#### Basic usage
---
### Formatting
The `_`/`format` store is the actual formatter method. To use it, it's simple as any other svelte store.
```html
<script>
// locale is en
import { _ } from 'svelte-i18n'
</script>
<input placeholder="{$_('greeting.ask')}" />
```
`svelte-i18n` uses `formatjs` behind the scenes, which means it supports the [ICU message format](http://userguide.icu-project.org/formatparse/messages) for interpolation, pluralization and much more.
```html
<div>
{$_('message')}: {$_('messages.success')}
<!-- Message: SUCCESS-->
{$_('greeting.message', { name: 'John' })}
<!-- Hello John, how are you? -->
{$_('photos', { n: 0 })}
<!-- You have no photos. -->
{$_('photos', { n: 12 })}
<!-- You have 12 photos. -->
</div>
```
#### Current locale
### Formatting methods
The current locale is available via `this.store.get().locale`.
#### `_` / `format`
#### Interpolation
`function(messageId: string, locale:? string): string`
`function(messageId: string, interpolations?: object, locale:? string): string`
Main formatting method that formats a localized message by its id.
```html
<div>
<!-- Named interpolation -->
{$_('greeting', { name: 'John' })}
<!-- Hello John, how are you?-->
<script>
import { _ } from 'svelte-i18n'
</script>
<!-- List interpolation -->
{$_('greetingIndex', ['John'])}
<!-- Hello John, how are you?-->
</div>
<div>{$_('greeting.ask')}</div>
<!-- Please type your name -->
```
#### Pluralization
#### `_.upper`
Transforms a localized message into uppercase.
```html
<div>
0 {$_.plural('meter', 0)}
<!-- 0 meters -->
<script>
import { _ } from 'svelte-i18n'
</script>
1 {$_.plural('meter', 1)}
<!-- 1 meter -->
100 {$_.plural('meter', 100)}
<!-- 100 meters -->
0 {$_.plural('book', 0)}
<!-- 0 books -->
1 {$_.plural('book', 1)}
<!-- 1 book -->
10 {$_.plural('book', 10)}
<!-- 10 books -->
</div>
<div>{$_.upper('greeting.ask')}</div>
<!-- PLEASE TYPE YOUR NAME -->
```
#### Utilities
#### `_.lower`
Transforms a localized message into lowercase.
```html
<div>
{$_.upper('message')}
<!-- MESSAGE -->
<script>
import { _ } from 'svelte-i18n'
</script>
{$_.lower('message')}
<!-- message -->
{$_.capital('message')}
<!-- Message -->
{$_.title('greeting', { name: 'John' })}
<!-- Hello John, How Are You?-->
</div>
<div>{$_.lower('greeting.ask')}</div>
<!-- PLEASE TYPE YOUR NAME -->
```
#### `_.capital`
Capitalize a localized message.
```html
<script>
import { _ } from 'svelte-i18n'
</script>
<div>{$_.capital('greeting.ask')}</div>
<!-- Please type your name -->
```
#### `_.title`
Transform the message into title case.
```html
<script>
import { _ } from 'svelte-i18n'
</script>
<div>{$_.capital('greeting.ask')}</div>
<!-- Please Type Your Name -->
```
#### `_.time`
`function(time: Date, format?: string, locale?: string)`
Formats a date object into a time string with the specified format (`short`, `medium`, `long`, `full`). Please refer to the [ICU message format](http://userguide.icu-project.org/formatparse/messages) documentation for all available. formats
```html
<script>
import { _ } from 'svelte-i18n'
</script>
<div>{$_.time(new Date(2019, 3, 24, 23, 45))}</div>
<!-- 11:45 PM -->
<div>{$_.time(new Date(2019, 3, 24, 23, 45), 'medium')}</div>
<!-- 11:45:00 PM -->
```
#### `_.date`
`function(date: Date, format?: string, locale?: string)`
Formats a date object into a string with the specified format (`short`, `medium`, `long`, `full`). Please refer to the [ICU message format](http://userguide.icu-project.org/formatparse/messages) documentation for all available. formats
```html
<script>
import { _ } from 'svelte-i18n'
</script>
<div>{$_.date(new Date(2019, 3, 24, 23, 45))}</div>
<!-- 4/24/19 -->
<div>{$_.date(new Date(2019, 3, 24, 23, 45), 'medium')}</div>
<!-- Apr 24, 2019 -->
```
#### `_.number`
`function(number: Number, locale?: string)`
Formats a number with the specified locale
```html
<script>
import { _ } from 'svelte-i18n'
</script>
<div>{$_.number(100000000)}</div>
<!-- 100,000,000 -->
<div>{$_.number(100000000, 'pt')}</div>
<!-- 100.000.000 -->
```

View File

@ -42,4 +42,4 @@
<br />
<button on:click={() => locale.set(oppositeLocale)}>
{$_('switch.lang', null, oppositeLocale)}
</button>
</button>

7
package-lock.json generated
View File

@ -1,6 +1,6 @@
{
"name": "svelte-i18n",
"version": "1.0.1-beta",
"version": "1.0.2-beta",
"lockfileVersion": 1,
"requires": true,
"dependencies": {
@ -5556,11 +5556,6 @@
}
}
},
"intl-format-cache": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/intl-format-cache/-/intl-format-cache-2.1.0.tgz",
"integrity": "sha1-BKNp/sv61tpgBbrh8UMzMy3PkxY="
},
"intl-messageformat": {
"version": "2.2.0",
"resolved": "https://registry.npmjs.org/intl-messageformat/-/intl-messageformat-2.2.0.tgz",

View File

@ -71,7 +71,6 @@
},
"dependencies": {
"deepmerge": "^3.2.0",
"intl-format-cache": "^2.1.0",
"intl-messageformat": "^2.2.0",
"micro-memoize": "^3.0.1",
"object-resolve-path": "^1.1.1"

View File

@ -1,31 +1,32 @@
import { writable, derived } from 'svelte/store'
import resolvePath from 'object-resolve-path'
import IntlMessageFormat from 'intl-messageformat'
import memoizeConstructor from 'intl-format-cache'
const capital = str => str.replace(/(^|\s)\S/, l => l.toUpperCase())
const title = str => str.replace(/(^|\s)\S/g, l => l.toUpperCase())
const upper = str => str.toLocaleUpperCase()
const lower = str => str.toLocaleLowerCase()
import memoize from 'micro-memoize'
import { capital, title, upper, lower } from './utils.js'
let currentLocale
let currentDictionary
const getMessageFormatter = memoizeConstructor(IntlMessageFormat)
const getMessageFormatter = memoize(
(message, locale, formats) => new IntlMessageFormat(message, locale, formats),
)
function lookupMessage(path, locale) {
// TODO improve perf here
const lookupMessage = memoize((path, locale) => {
return (
currentDictionary[locale][path] ||
resolvePath(currentDictionary[locale], path)
)
}
})
function formatMessage(message, interpolations, locale = currentLocale) {
const formatMessage = (message, interpolations, locale = currentLocale) => {
return getMessageFormatter(message, locale).format(interpolations)
}
function getLocalizedMessage(path, interpolations, locale = currentLocale) {
const getLocalizedMessage = (path, interpolations, locale = currentLocale) => {
if (typeof interpolations === 'string') {
locale = interpolations
interpolations = undefined
}
const message = lookupMessage(path, locale)
if (!message) return path

6
src/utils.js Normal file
View File

@ -0,0 +1,6 @@
export const capital = str => str.replace(/(^|\s)\S/, l => l.toUpperCase())
export const title = str => str.replace(/(^|\s)\S/g, l => l.toUpperCase())
export const upper = str => str.toLocaleUpperCase()
export const lower = str => str.toLocaleLowerCase()

View File

@ -1,174 +1,110 @@
// TODO: A more serious test
import { dictionary, locale } from '../src/index'
import { dictionary, locale, format } from '../src/index'
import { capital, title, upper, lower } from '../src/utils'
dictionary.set({
'pt-br': {
test: 'teste',
phrase: 'adoro banana',
phrases: ['Frase 1', 'Frase 2'],
pluralization: 'Zero | Um | Muito!',
simplePluralization: 'Singular | Plural',
interpolation: {
key: 'Olá, {0}! Como está {1}?',
named: 'Olá, {name}! Como está {time}?',
},
interpolationPluralization: 'One thingie | {0} thingies',
wow: {
much: {
deep: {
list: ['Muito', 'muito profundo'],
},
},
},
obj: {
a: 'a',
b: 'b',
let _
let currentLocale
const dict = {
pt: {
hi: 'olá você',
'switch.lang': 'Trocar idioma',
greeting: {
ask: 'Por favor, digite seu nome',
message: 'Olá {name}, como vai?',
},
photos:
'Você {n, plural, =0 {não tem fotos.} =1 {tem uma foto.} other {tem # fotos.}}',
cats: 'Tenho {n, number} {n,plural,=0{gatos}one{gato}other{gatos}}',
},
en: {
hi: 'hi yo',
'switch.lang': 'Switch language',
greeting: {
ask: 'Please type your name',
message: 'Hello {name}, how are you?',
},
photos:
'You have {n, plural, =0 {no photos.} =1 {one photo.} other {# photos.}}',
cats: 'I have {n, number} {n,plural,one{cat}other{cats}}',
},
}
format.subscribe(formatFn => {
_ = formatFn
})
dictionary.set(dict)
locale.subscribe(l => (currentLocale = l))
locale.set('pt')
it('should change locale', () => {
locale.set('pt')
expect(currentLocale).toBe('pt')
locale.set('en')
expect(currentLocale).toBe('en')
})
locale.set('pt-br')
describe('Localization', () => {
beforeEach(() => {
console.error = jest.fn()
})
afterEach(() => {
console.error.mockRestore()
})
it('should start with a clean store', () => {
const { _, locale } = store.get()
expect(locale).toBeFalsy()
expect(_).toBeFalsy()
})
it('should change the locale after a "locale" store event', () => {
store.fire('locale', 'pt-br')
const { locale, _ } = store.get()
expect(locale).toBe('pt-br')
expect(_).toBeInstanceOf(Function)
})
it('should have a .i18n.setLocale() method', () => {
expect(store.i18n.setLocale).toBeInstanceOf(Function)
store.i18n.setLocale('pt-br')
const { locale } = store.get()
expect(locale).toBe('pt-br')
})
it('should handle nonexistent locale', () => {
expect(store.i18n.setLocale('foo'))
expect(console.error).toHaveBeenCalledTimes(1)
})
it('should return the message id when no message identified by it was found', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(_('non.existent')).toBe('non.existent')
})
it('should get a message by its id', () => {
const { _ } = store.get()
expect(_('test')).toBe(locales['pt-br'].test)
})
it('should get a deep nested message by its string path', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(_('obj.b')).toBe('b')
})
it('should get a message within an array by its index', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(_('phrases[1]')).toBe(locales['pt-br'].phrases[1])
/** Not found */
expect(_('phrases[2]')).toBe('phrases[2]')
})
it('should interpolate with {numeric} placeholders', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(_('interpolation.key', ['Chris', 'o dia'])).toBe(
'Olá, Chris! Como está o dia?',
)
})
it('should interpolate with {named} placeholders', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(
_('interpolation.named', {
name: 'Chris',
time: 'o dia',
}),
).toBe('Olá, Chris! Como está o dia?')
})
it('should handle pluralization with _.plural()', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(_.plural('simplePluralization')).toBe('Plural')
expect(_.plural('simplePluralization', 1)).toBe('Singular')
expect(_.plural('simplePluralization', 3)).toBe('Plural')
expect(_.plural('simplePluralization', -23)).toBe('Plural')
expect(_.plural('pluralization')).toBe('Zero')
expect(_.plural('pluralization', 0)).toBe('Zero')
expect(_.plural('pluralization', 1)).toBe('Um')
expect(_.plural('pluralization', -1)).toBe('Um')
expect(_.plural('pluralization', -1000)).toBe('Muito!')
expect(_.plural('pluralization', 2)).toBe('Muito!')
expect(_.plural('pluralization', 100)).toBe('Muito!')
expect(_.plural('interpolationPluralization', 1)).toBe('One thingie')
expect(_.plural('interpolationPluralization', 10, [10])).toBe('10 thingies')
})
it('should fallback to message id if id is not found', () => {
expect(_('batatinha')).toBe('batatinha')
})
describe('Localization utilities', () => {
it('should translate to current locale', () => {
locale.set('pt')
expect(_('switch.lang')).toBe('Trocar idioma')
locale.set('en')
expect(_('switch.lang')).toBe('Switch language')
})
it('should translate to passed locale', () => {
expect(_('switch.lang', 'pt')).toBe('Trocar idioma')
expect(_('switch.lang', 'en')).toBe('Switch language')
})
it('should interpolate message with variables', () => {
expect(_('greeting.message', { name: 'Chris' })).toBe(
'Hello Chris, how are you?',
)
})
it('should interpolate message with variables according to passed locale', () => {
expect(_('greeting.message', { name: 'Chris' }, 'pt')).toBe(
'Olá Chris, como vai?',
)
})
describe('utilities', () => {
beforeAll(() => {
locale.set('en')
})
it('should capital a translated message', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(capital('Adoro banana')).toBe('Adoro banana')
expect(_.capital('phrase')).toBe('Adoro banana')
expect(_.capital('hi')).toBe('Hi yo')
})
it('should title a translated message', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(title('Adoro Banana')).toBe('Adoro Banana')
expect(_.title('phrase')).toBe('Adoro Banana')
expect(_.title('hi')).toBe('Hi Yo')
})
it('should lowercase a translated message', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(lower('adoro banana')).toBe('adoro banana')
expect(_.lower('phrase')).toBe('adoro banana')
expect(_.lower('hi')).toBe('hi yo')
})
it('should uppercase a translated message', () => {
store.i18n.setLocale('pt-br')
const { _ } = store.get()
expect(upper('ADORO BANANA')).toBe('ADORO BANANA')
expect(_.upper('phrase')).toBe('ADORO BANANA')
expect(_.upper('hi')).toBe('HI YO')
})
const date = new Date(2019, 3, 24, 23, 45)
it('should format a time value', () => {
locale.set('en')
expect(_.time(date)).toBe('11:45 PM')
expect(_.time(date, 'medium')).toBe('11:45:00 PM')
})
it('should format a date value', () => {
expect(_.date(date)).toBe('4/24/19')
expect(_.date(date, 'medium')).toBe('Apr 24, 2019')
})
// number
it('should format a date value', () => {
expect(_.number(123123123)).toBe('123,123,123')
})
})