<aside> 💡

Please provide improvements and be patient with this document as we work through all the different use cases when it comes to localizing strings in the web UI.

</aside>

Overview

Because we support localization, adding text is a little more complicated than just typing it on the page. It’s all a part of a maturing project. But once you do it a couple of times, you’ll have it figured out.

We use the following tools to accomplish this, but you don’t have to worry about most of them.

Tooling

Tool Description
Owncast Translation Component Custom component used for displaying translated strings.
i18next Used for parsing and exporting translatable strings from our source code.
next-export-i18n Used to handle localization for Next.js statically exported sites.
Cowdin Web service used for performing the actual translation of strings. Users can create accounts to assist in the translation process.

There’s two parts to understand when adding a new translated string:

  1. The key referring to the string. Each of the languages will refer to this key when translating.
  2. The string itself you want to display.

Adding a new translatable key

The first thing you must do when creating a new translatable string is to assign it a key.

  1. Open localization.ts
  2. Find the existing section (known as a namespace) you want to add the new string to (Admin → EditInstanceDetails, for example).
  3. If this section doesn’t already exist, create it under Frontend or Admin respectively.
  4. Create a new key with a reasonable name and value. For example: helloWorld: ‘Admin.EditInstanceDetails.HelloWorld’ for a new piece of text that says “Hello, world” in the Edit Instance Details section of the Admin.

Use the Translation component

For most cases where you want to display a string in the web interface, you will be using the Translation component. You don’t have to know how it’s built or internally how it works. But simply how to use it. It’s the easiest and fastest way to get things done.