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	18%

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:"
  },
  "avatar": {
    "ariaLabel": "Avatar of {fullName}"
  }
}

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.

main.ts

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

main.ts

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.

Only for your project

import type { OnyxTranslations } from "sit-onyx";

const myCustomLanguage: OnyxTranslations = {
  // add your translations here...
  someMessage: "Hello World",
};

When contributing to onyx

// 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"
}