svelte-i18n/docs/Migration.md

• From v2 to v3
  • Formatting numbers, dates and times
  • Casing utilities
  • Getting the client locale
• From v1 to v2
  • Adding dictionaries
  • Setting the initial and fallback locales
  • Interpolating values
  • Adding custom formats

From v2 to v3

Formatting numbers, dates and times

In v2, to format numbers, dates and times you would access the date, time or number method of the main formatter method:

$_.time(dateValue)
$_.date(dateValue)
$_.number(100000000)

In v3, these utilities are exported as standalone formatter stores, making them tree-shakeable:

import { time, date, number } from 'svelte-i18n'

$time(someDateValue)
$date(someDateValue)
$number(100000000)

Casing utilities

The casing utilities $_.title, $_.capital, $_.lower, $_.upper were removed from the library.

In v2:

$_.lower('message.id')
$_.upper('message.id')
$_.title('message.id')
$_.capital('message.id')

In v3:

function capital(str: string) {
  return str.replace(/(^|\s)\S/, l => l.toLocaleUpperCase())
}

function title(str: string) {
  return str.replace(/(^|\s)\S/g, l => l.toLocaleUpperCase())
}

$_('message.id').toLocaleLowerCase()
$_('message.id').toLocaleUpperCase()
title($_('message.id'))
capital($_('message.id'))

Getting the client locale

In v2, the init method could automatically set the initial locale based on some heuristcs from the client:

import { init } from 'svelte-i18n'

init({
  initialLocale: {
    navigator: true,
  },
})

However, many people didn't need that kind of extra weight in their apps. So in v3 you have to explicitly import the utility desired:

• getLocaleFromHostname
• getLocaleFromPathname
• getLocaleFromNavigator
• getLocaleFromQueryString
• getLocaleFromHash

import { init, getLocaleFromNavigator } from 'svelte-i18n'

init({
  initialLocale: getLocaleFromNavigator(),
})

From v1 to v2

Adding dictionaries

In v1, dictionaries were added through the store API of $dictionary.

import { dictionary } from 'svelte-i18n'

dictionary.set({
  en: { ... },
  pt: { ... },
})

dictionary.update(d => {
  d.fr = { ... }
  return d
})

In v2, you can use addMessages(locale, messages) to add new messages to the main dictionary.

import { addMessages } from 'svelte-i18n'

addMessages('en', { ... })
addMessages('pt', { ... })
addMessages('fr', { ... })

// message dictionaries are merged together
addMessages('en', { ... })

It's also possible to asynchronously load your locale dictionary, see register().

Setting the initial and fallback locales

In v1, to set the initial and fallback locales you could use getClientLocale() together with $locale = ... or locale.set(...).

import { getClientLocale, locale } from 'svelte-i18n'

locale.set(
  getClientLocale({
    fallback: 'en',
    navigator: true,
  })
)

In v2, both locales can be defined very similarly with init().

import { init } from 'svelte-i18n'

init({
  fallbackLocale: 'en',
  initialLocale: {
    navigator: true,
  },
})

Interpolating values

In v1, interpolated values were the whole object passed as the second argument of the $format method.

<h1>
  {$_('navigation.pagination', { current: 2, max: 10 })}
</h1>
<!-- Page: 2/10 -->

In v2, the interpolated values are passed in the values property.

<h1>
  {$_('navigation.pagination', { values: { current: 2, max: 10 }})}
</h1>
<!-- Page: 2/10 -->

Adding custom formats

In v1, custom formats could be added with addCustomFormats().

import { addCustomFormats } from 'svelte-i18n'

addCustomFormats({
  number: {
    EUR: { style: 'currency', currency: 'EUR' },
  },
})

In v2, custom formats are added through init().

import { init } from 'svelte-i18n'

init({
  fallbackLocale: ...,
  initialLocale, ...,
  formats:{
    number: {
      EUR: { style: 'currency', currency: 'EUR' },
    },
  }
})