Version 3

[ivanhofer]

Version 3 is here 🎉

This release contains some breaking changes:

• locales have to be loaded in a separate step
• remove loadLocalesAsync option from generator
• formatters have to be initialized synchronously

migrating from version 2.x.x

1. if set, remove the loadLocalesAsync option from your .typesafe-i18n.json config file:

   {
      "$schema": "https://unpkg.com/typesafe-i18n@2.60.2/schema/typesafe-i18n.json",
   -  "loadLocalesAsync": true,
      "adapter": "svelte"
   }

2. if you are using the asynchronous initializing of formatters inside src/i18n/formatters.ts, you have to switch to synchronous initializing:

   -import type { AsyncFormattersInitializer } from 'typesafe-i18n'
   +import type { FormattersInitializer } from 'typesafe-i18n'
   import type { Locales, Formatters } from './i18n-types'
   import { date } from 'typesafe-i18n/formatters'
   
   -export const initFormatters: AsyncFormattersInitializer<Locales, Formatters> = async (locale: Locales) => {
   +export const initFormatters: FormattersInitializer<Locales, Formatters> = (locale: Locales) => {
      const formatters: Formatters = {
         //
      }
   
      return formatters
   }

3. manually load locales in places where you initialize typesafe-i18n or change the locale:

   import { loadLocaleAsync } from './i18n/i18n-util.async'
   
   const switchLocale = async (locale) => {
   -  await setLocale(locale)
   +  await loadLocaleAsync(locale)
   +  setLocale(locale)
   }

4. if you are using the svelte adapter and are using the LL store outside of Svelte components, you need to make sure you are accessing the store correctly:

   +import { get } from 'svelte/store'
   import LL from '$i18n/i18n-svelte'
   
   function example(): string {
   -   return LL.HI({ year: 2021 });
   +   return get(LL).HI({ year: 2021 })
   }

   see Version 3 and 4 broke loading data from LL in scripts #180

   Previously it was also possible to access the translation directly on the LL store itself, but this function was removed to simplify the implementation.

reasons for these changes:

These changes were made due to this issue.
In version 3.0.0 it is now possible to switch locales with a synchronous function. In the SvelteKit example it can be called before the first component renders, resulting in having a consistent locale state while rendering the page on the server for SSR.

It always felt a bit strange to have to choose between loading the locales in a synchronous way or loading them asnchronously. You had to specify the flag loadLocalesAsync in the options and the generator then created a different code whether it was set to true or false.
Use-cases where you would need both variants (e.g. a shared dictionary for API and frontend) would require you to write some manual code. Beginning with version 3 the generator now exports code to handle both loading variants. You then can choose between both options.

An advantage that also comes with splitting the loading and the initialization of the adapters is: you can now load a dictionary before initializing your application.

downside: developers have to manually call a function to load locales before using the locale. But it's just a single line to add to the code.