Skip to content

Language Translations

Jump to bottom
Michael Brown edited this page Apr 13, 2023 · 1 revision

Binner now has support for alternate languages other than english.

We need your help - if you are fluent in other languages and willing to contribute a small amount of time we would love your assistance.

How to translate from English to another language

Binner uses i18next to perform translations of the frontend javascript application. It uses strings located in a single json file for each language.

Translations can be performed by downloading locales/en/translations.json and converting each string definition to your language.

All translation files are located in Binner/Binner.Web/ClientApp/public/locales/{language}

Submitting your translated file

Submissions can be done via Pull Request or by posting the file as a New Issue .

Document Details

The translations.json file is a json formatted file. It consists of a nested structure that can be translated by the application via a path name.

Example:

{
  "page": {
    "home": {
      "message": {
        "title": "Home page title",
        "description": "Welcome to the home page"
      }
    }
  }
}

For the frontend application to get the title of the home page, it would look up the following path: page.home.message.title. Each nested item translates to a path making it very easy for the application to locate the strings it needs.

Document Structure

Our structure is generally the following:

{
  "page": { // all page specific translations },
  "bc": { // all breadcrumb navigation trails }
  "comp": { // all component specific translations },
  "button": { // all global buttons },
  "label": { // all global labels (form labels, table headers) },
  "message": { // all global info messages },
  "confirm": { // confirmation popup modals },
  "error": { // system errors },
  "success": { // success messages },
  "popup": { // tooltip popups },
  "footer": { // website footer },
  "notification": { // global notifications },
  "color": { // color names }
}

There are exceptions to the rule as each page (page) /component (comp) may have its own label/popup/confirm/error messages at the discretion of the developer. Where certain strings are used in multiple places we tend to put them in the global sections instead of dedicated to the page.

Formatting

There are times when strings are part of dynamic content, such as the number of items in an object that needs to be displayed or some formatting needs to be inserted such as a web link or html tags. Simple variable keywords are used, and container tags for more complex needs.

Variable Keywords

There are 15 {{count}} parts

This is a pretty straightforward use where the number of parts will be replaced by the {{count}} tag. Do not translate/modify these as they are used by the application!

Formatting elements

Select an <1>item</1> with <3>optional</3> description. <5/><6/>This is a new line!

This shows a more complicated layout which would be translated by the application as the following HTML:

Select an <b>item</b> with <i>optional</i> description. <br/><br/>This is a new line!

Each numbered section indicates a segment in the text. A segment is defined as section of text, or a tag, or a tag that contains text. For example:

  • Select an is considered segment 0
  • <b></b> is considered segment 1 and can contain text
  • with is segment 2, optional is segment 3 and can contain text
  • description. is segment 4
  • <br/> is segment 5
  • <br/> is segment 6
  • This is a new line! is segment 7

The segments can be moved to contain the equivalent translated content, but should never be removed.

Additions of new translation keys

Binner logs missing translation keys to Binner.MissingLocaleKeys.log in the logs folder you have configured (Windows Default: C:\Binner, Unix Default: ./)

It is important to note that if the translation file for a language contains the keys, but they are in English, they will not be logged as missing as it doesn't know what language the text is in.

The log file will indicate the language, key path and english default text.

2023-04-12|Missing Translations | it | /settings
2023-04-12|[it] page.settings.popup.swarmApiUrl                    "Swarm's API Url"
2023-04-12|[it] page.settings.popup.forgetCredentials              "Forget any cached credentials and force reauthentication with DigiKey"
2023-04-12|[it] page.settings.popup.printerPartLabelSource         "Your printer name as it appears in Windows, or CUPS (Unix)."
2023-04-12|[it] page.settings.popup.arrowApiKey                    "Your api key for Arrow."
2023-04-12|[it] page.settings.popup.octopartClientSecret           "Your Client Secret for Octopart/Nexar."

Getting help with a translation

If you have questions in regards to performing translations, feel free to send a message to the Translation Discussion group. And many thanks!

Clone this wiki locally