This package has changed name, was previously @soleil-api/i18n.
More information

@soleil-se/i18n

Install

npm i @soleil-se/i18n

Example

Create translations, can be in seperate json or js files or in the initialization file. Language is determined automatically from PortletContextUtil.getCurrentLocale() on the server and document.documentElement.lang on the client.

For simpler translations you can put them in a single file.

import { createI18n } from '@soleil-se/i18n';

export default createI18n({
  en: {
    hello: 'Hello'
  },
  sv: {
    hello: 'Hej'
  },
});

But it’s also possible to split them up in different files.

import { createI18n } from '@soleil-se/i18n';

import en from './en';
import sv from './sv';

export default createI18n({ en, sv });

Before 2.4.0

import { addMessages, translate } from '@soleil-se/i18n';

import en from './en';
import sv from './sv';

addMessages('en', en);
addMessages('sv', sv);

export default translate;

export default {
  hello: 'Hello',
};

export default {
  hello: 'Hej',
};

Then import the i18n.js file where you need to translate.

import i18n from './i18n';

console.log(i18n('hello'));

<script>
  import i18n from './i18n';
</script>

<h1>{i18n('hello')}</h1>

RESTApp Since 2.5.2

In a RESTApp you can’t determine the locale so you need to set it manually in your route.
Will fall back to en if locale cannot be determined.

import router from '@sitevision/api/common/router';
import { setLocale } from '@soleil-se/i18n';

import i18n from './i18n';

router.get('/sv', (req, res) => {
  setLocale('sv');
  res.json({
    hello: i18n('hello'),
  });
});

router.get('/en', (req, res) => {
  setLocale('en');
  res.json({
    hello: i18n('hello'),
  });
});

API

createI18n([messages])

This function creates a new i18n instance.

Param	Type	Default	Description
[messages]	`object`	`{}`	Initial messages.

Returns: i18n - i18n instance.

Add messages when creating a new instance.

import { createI18n } from '@soleil-se/i18n';

export default createI18n({
  en: {
    hello: 'Hello'
  },
  sv: {
    hello: 'Hej'
  },
});

import { createI18n } from '@soleil-se/i18n';

export default createI18n({
  en: {
    hello: 'Hello {name}!'
  },
  sv: {
    hello: 'Hej {name}!'
  },
});

i18n(path, [values]) ⇨ `string`

Translate a message.

Returns: string - Translated message.

Param	Type	Default	Description
path	`string`		Path to message key.
[values]	`object`	`{}`	Values to inject in message.

import i18n from './i18n';
console.log(i18n('hello')); // Hej

import i18n from './i18n';
console.log(i18n('hello', { name: 'Foo' })); // Hej Foo!

i18n.addMessages(locale, messages)

Add a locale with messages.

Param	Type	Description
locale	`string`	Locale key.
messages	`Object`	Messages object.

import { createI18n } from '@soleil-se/i18n';

const i18n = createI18n();

i18n.addMessages('en', { hello: 'Hello' });
i18n.addMessages('sv', { hello: 'Hej' });

return i18n;

Is also chainable.

import { createI18n } from '@soleil-se/i18n';

return createI18n()
  .addMessages('en', { hello: 'Hello' })
  .addMessages('sv', { hello: 'Hej' });

i18n.setMessages(messages)

Sets all messages.

Param	Type	Description
messages	`Object`	Messages object with locale keys at top level.

import { createI18n } from '@soleil-se/i18n';

const i18n = createI18n();

i18n.setMessages({
  en: { hello: 'Hello' },
  sv: { hello: 'Hej'},
});

return i18n;

i18n.getMessages()

Get all messages for current locale as an object.

import { createI18n } from '@soleil-se/i18n';

return createI18n({
  en: { hello: 'Hello' },
  sv: { hello: 'Hej' },
});

import i18n from './i18n';

console.log(i18n.getMessages());

i18n.messageExists(path)

Check if a translation for a message exists or not for the current locale.

Returns: boolean - If translation of message exists or not.

Param	Type	Description
path	`string`	Path to message key.

import { createI18n } from '@soleil-se/i18n';

return createI18n({
  en: { hello: 'Hello' },
  sv: { hello: 'Hej' },
});

import i18n from './i18n';

console.log(i18n.messageExists('hello'));

i18n.translate(path, [values]) ⇨ `string`

Translate a message.

Returns: string - Translated message.

Param	Type	Default	Description
path	`string`		Path to message key.
[values]	`object`	`{}`	Values to inject in message.

import i18n from './i18n';
console.log(i18n.translate('hello')); // Hej

import i18n from './i18n';
console.log(i18n.translate('hello', { name: 'Foo' })); // Hej Foo!

setLocale(locale)

Set locale to be used when translating

Param	Type	Description
locale	`any`	Can be anything that resolves to a locale string.

import { setLocale } from '@soleil-se/i18n';

setLocale('sv');

getLocale() ⇨ `string`

Get current locale as string.

Returns: string - Current locale.

import { getLocale } from '@soleil-se/i18n';

if(getLocale() === 'sv') {
  console.log('Här vare svenskt!');
}

addMessages(locale, messages)

Add a locale with messages.

Param	Type	Description
locale	`string`	Locale key.
messages	`Object`	Messages object.

import { addMessages } from '@soleil-se/i18n';

addMessages('en', { hello: 'Hello'});
addMessages('sv', { hello: 'Hej'});

setMessages(messages)

Sets all messages.

Param	Type	Description
messages	`Object`	Messages object with locale keys at top level.

import { setMessages } from '@soleil-se/i18n';

setMessages({
  en: { hello: 'Hello' },
  sv: { hello: 'Hej'},
});

getMessages()

Get all messages for current locale as an object.

import { getMessages } from '@soleil-se/i18n';

console.log(getMessages());

messageExists(path)

Check if a translation for a message exists or not for the current locale.

Returns: boolean - If translation of message exists or not.

Param	Type	Description
path	`string`	Path to message key.

import { messageExists } from '@soleil-se/i18n';

console.log(messageExists('hello'));

translate(path, [values]) ⇨ `string`

Translate a message. Also exported as i18n and t.

Returns: string - Translated message.

Param	Type	Default	Description
path	`string`		Path to message key.
[values]	`object`	`{}`	Values to inject in message.

import { addMessages, translate, i18n, t } from '@soleil-se/i18n';

addMessages('en', { hello: 'Hello'});
addMessages('sv', { hello: 'Hej'});

console.log(translate('hello'));
console.log(i18n('hello'));
console.log(t('hello'));

With values

import { addMessages, i18n } from '@soleil-se/i18n';

addMessages('en', { hello: 'Hello {name}!'});
addMessages('sv', { hello: 'Hej {name}!'});

console.log(i18n('hello', { name: 'Foo' })); // Hej Foo!

Svelte

If you only need static translations without changing anything on the fly the base API is enough. There is a store wrapper when language needs to be changed dynamically.

Static

Demo https://svelte.dev/repl/35e4069f38b14b7891fd8fd0ce571dfd?version=4.2.11

Dynamic

Demo https://svelte.dev/repl/b17f963e58154b6cb2e211973e561692?version=4.2.11

import { addMessages, i18n, setLocale } from '@soleil-se/i18n/svelte-store';

import en from './en';
import sv from './sv';

addMessages('en', en);
addMessages('sv', sv);

export { i18n, setLocale };

<script>
  import { i18n, setLocale } from './i18n';

  let name = 'Foo';
</script>

<h1>Dynamic</h1>
<button on:click={() => setLocale('en')}>
  English
</button>
<button on:click={() => setLocale('sv')}>
  Svenska
</button>

<label for="name_input">{$i18n('name')}</label>
<input id="name_input" bind:value={name} />

<h2>{$i18n('hello')}</h2>
<p>
  {$i18n('howAreYou', { name })}
</p>

Bundled script module

Since you can’t call a function in a Velocity template you need to use the i18n.getMessages function to export an object with translated messages.
Injecting values to messages won’t work with this method.
Also prefix the i18n file with underscore, _i18n.js.

import { createI18n } from '@soleil-se/i18n';

return createI18n({
  en: { hello: 'Hello' },
  sv: { hello: 'Hej' },
}).getMessages();

Before 2.4.0

import { addMessages, getMessages } from '@soleil-se/i18n';

addMessages('en', { hello: 'Hello'});
addMessages('sv', { hello: 'Hej'});

export default getMessages();

import i18n from './_i18n';

export default {
  i18n,
};

<p>${i18n.hello}</p>

@soleil-se/i18n

Install

Example

RESTApp Since 2.5.2

API

createI18n([messages])

i18n(path, [values]) ⇨ string

i18n.addMessages(locale, messages)

i18n.setMessages(messages)

i18n.getMessages()

i18n.messageExists(path)

i18n.translate(path, [values]) ⇨ string

setLocale(locale)

getLocale() ⇨ string

addMessages(locale, messages)

setMessages(messages)

getMessages()

messageExists(path)

translate(path, [values]) ⇨ string

Svelte

Static

Dynamic

Bundled script module

i18n(path, [values]) ⇨ `string`

i18n.translate(path, [values]) ⇨ `string`

getLocale() ⇨ `string`

translate(path, [values]) ⇨ `string`