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 | 19% |
Which texts are translated?
Below you can find all translatable texts that are used by our components.
{
"optional": "(optional)",
"cancel": "Cancel",
"apply": "Apply",
"back": "Back",
"close": "Close",
"dataGrid": {
"head": {
"sorting": {
"action": {
"asc": "Sort the table ascending by the {field} column.",
"desc": "Sort the table descending by the {field} column.",
"none": "Reset sorting."
},
"menu": {
"asc": "Sort ascending",
"desc": "Sort descending",
"none": "No sorting"
}
}
}
},
"validations": {
"tooShort": {
"preview": "Too short, minimum {minLength} characters required",
"fullError": "Make the input at least {minLength} characters long. It is currently {n} characters long. Special characters might use more than one character."
},
"tooLong": {
"preview": "Too long, maximum {maxLength} characters allowed",
"fullError": "Shorten the input to {maxLength} characters or less. It is currently {n} characters long. Special characters might use more than one character."
},
"rangeUnderflow": {
"preview": "Too low",
"fullError": "Input value must be greater than or equal to {min}."
},
"rangeOverflow": {
"preview": "Too high",
"fullError": "Input value must be less than or equal to {max}."
},
"patternMismatch": {
"preview": "Invalid format",
"fullError": "Please match the format requested."
},
"valueMissing": {
"preview": "Required",
"fullError": "The field is empty, it is mandatory and must be filled in."
},
"stepMismatch": {
"preview": "Invalid number",
"fullError": "Please enter a valid number, that is a multiple of {step}."
},
"badInput": {
"preview": "Invalid input",
"fullError": "\"{value}\" does not match the expected type."
},
"typeMismatch": {
"generic": {
"preview": "Invalid input type",
"fullError": "\"{value}\" does not match the expected type."
},
"email": {
"preview": "Invalid mail",
"fullError": "\"{value}\" is not a valid email address. It should be similar to \"johndoe@example.com\" (Must contain one @ symbol and a period)."
},
"number": {
"preview": "Invalid number",
"fullError": "\"{value}\" is not a valid number. Make sure it contains only digits, and optionally a single decimal point."
},
"tel": {
"preview": "Invalid phone number",
"fullError": "\"{value}\" is not a valid phone number."
},
"url": {
"preview": "Invalid URL",
"fullError": "\"{value}\" is not a valid URL. A URL usually points to a website and should be similar to \"https://www.example.com\"."
}
}
},
"select": {
"toggleDropDown": "Toggle selection popover",
"empty": "No data available",
"noMatch": "No item matches your search",
"searchInputLabel": "Filter the list items",
"clearSearch": "Clear search filter",
"searchPlaceholder": "Search"
},
"selections": {
"selectAll": "Select all",
"currentSelection": "{n} selected"
},
"stepper": {
"decrement": "Decrement by {stepSize}",
"increment": "Increment by {stepSize}"
},
"table": {
"empty": "This table is empty."
},
"link": {
"opensExternally": "Opens in a new tab."
},
"navItemOptionsLabel": "Subpages of {label}",
"navigation": {
"appLogo": "App logo of {appName}",
"goToHome": "Go to home page",
"goBack": "Go back",
"userMenuLabel": "User options",
"toggleBurgerMenu": "Toggle burger menu",
"toggleContextMenu": "Toggle context menu",
"navigationHeadline": "Navigation",
"moreActionsFlyout": "Choose an action for the column \"{column}\"",
"moreActionsTrigger": "Toggle column actions"
},
"tooltip": {
"neutral": "Toggle info tooltip",
"danger": "Toggle error tooltip",
"success": "Toggle success tooltip"
},
"colorScheme": {
"headline": "Change appearance",
"subtitle": "Select the appearance of the application:",
"appearance": "Appearance",
"auto": {
"label": "Auto",
"description": "The application automatically adapts its appearance to your system settings."
},
"light": {
"label": "Light",
"description": "Light mode provides optimal contrast for bright environments."
},
"dark": {
"label": "Dark",
"description": "This color mode is optimized for darker environments."
}
},
"pagination": {
"label": "Pagination",
"ofPages": "of 1 page | of {n} pages",
"previous": "previous page",
"next": "next page",
"select": {
"label": "Page selection",
"listLabel": "Available pages"
}
},
"input": {
"clear": "Clear input"
},
"dialog": {
"close": "Close dialog"
},
"headline": {
"copyLink": "Copy link to this headline",
"copyLinkTo": "Copy link to headline:"
}
}
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
.
Using onyx with Nuxt
You don't need to configure i18n yourself if you're using onyx inside a Nuxt application with our @sit-onyx/nuxt module. For more information please see: Nuxt module
Custom translations
You can customize specific messages or even provide a whole custom language with 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"
}