Internationalization
onyx supports internationalization out-of-the-box. This includes commonly used translations that are used by our onyx components like texts for cancel / confirm buttons or "No data" scenarios.
Default translations
English is always supported so you don't need to do anything if you only need English texts.
Build-in languages
Name | Code | Translated keys |
---|---|---|
German (Germany) | de-DE | 100% |
American English | en-US | 100% |
Korean (South Korea) | ko-KR | 71% |
Which texts are translated?
Below you can find all translatable texts that are used by our components.
{
"optional": "(optional)",
"validations": {
"tooShort": "Please lengthen this text to {minLength} characters or more (you are currently using 1 character) | Please lengthen this text to {minLength} characters or more (you are currently using {n} characters)",
"tooLong": "Please shorten this text to {maxLength} characters or less (you are currently using 1 character) | Please shorten this text to {maxLength} characters or less (you are currently using {n} characters)",
"rangeUnderflow": "Value must be greater than or equal to {min}",
"rangeOverflow": "Value must be less than or equal to {max}",
"patternMismatch": "Please match the format requested.",
"valueMissing": "Please fill in this field.",
"stepMismatch": "Please enter a value that is a multiple of {step}.",
"badInput": "\"{value}\" does not match the expected type.",
"typeMismatch": {
"generic": "\"{value}\" does not match the expected type.",
"email": "\"{value}\" must be a valid email address.",
"number": "\"{value}\" must be a number.",
"tel": "\"{value}\" must be a valid phone number.",
"url": "\"{value}\" must a valid URL."
}
},
"selections": {
"selectAll": "Select all",
"currentSelection": "{n} selected"
},
"empty": "No data available",
"navItemOptionsLabel": "Subpages of {label}",
"navigation": {
"appLogo": "App logo",
"goBack": "Go back",
"userMenuLabel": "User options"
}
}
Usage
You need to globally provide the i18n translations and locale for onyx. We assume that you are already using some third-party library such as vue-i18n
for managing your app translations so onyx will integrate nicely into your setup.
import { createOnyx } from "sit-onyx";
import onyxDeDE from "sit-onyx/locales/de-DE.json";
// your project translation setup
import { useI18n } from "vue-i18n";
import enUS from "./i18n/locales/en-US.json";
import deDE from "./i18n/locales/de-DE.json";
const i18n = createI18n({
legacy: false,
locale: "en-US",
messages: { "en-US": enUS, "de-DE": deDE },
});
const onyx = createOnyx({
i18n: {
// The onyx locale will be updated whenever your vue-i18n locale changes
locale: i18n.global.locale,
// make sure that the key for each language is the same that you are using
// for your vue-i18n JSON files
messages: { "de-DE": onyxDeDE },
},
});
createApp(App).use(i18n).use(onyx).mount("#app");
That's it. All built-in component texts are now available in English (default) and German. The locale is synced with vue-i18n
.
Custom translations
You can customize specific messages or even provide a whole custom language will full TypeScript support.
Some messages also support pluralization or placeholders for values. Please take a look at the English texts to see which format is used for a specific message.
Change a single message
import enUS from "sit-onyx/locales/en-US.json";
enUS.someMessage = "Custom translation";
const onyx = createOnyx({
i18n: {
// ...
messages: { "en-US": enUS },
},
});
Additional languages
You can add a whole new language with full TypeScript support. But please note that you might need to manually update any keys that we might add/remove in the future.
Contribution
We are open for accepting community contributions, if you want to add a missing language, feel free to create a Pull request so all onyx users can benefit from it. You can simply add the translations inside the locales folder.
import type { OnyxTranslations } from "sit-onyx";
const myCustomLanguage: OnyxTranslations = {
// add your translations here...
someMessage: "Hello World",
};
// simply create a new json file for your language (e.g. "fr-FR")
// in the locales folder linked above and place your translations there
{
"someMessage": "Bonjour le monde"
}