Localize the client/browser UI with inlang paraglide-js

[IDisposable]

Localization

The browser/client frontend uses the paraglide-js plug-in from the inlang.com project to allow compile-time validated localization of all user-facing UI strings in the browser/client UI. This includes title, text, name, description, placeholder, label, aria-label, message attributes (such as confirmText, unit, badge, tag, or flag), HTML element text (such as <h?>, <span>, or <p> elements), notifications messages, and option label strings, etc.

We do not translate the console log messages, CSS class names, theme names, nor the various value strings (e.g. for value/label pair options), nor URL routes.

The localizations are stored in .json files in the ui/localizations/messages directory, with one language-per-file using the ISO 3166-1 alpha-2 country code (e.g. en for English, de for German, etc.)

m-function-matcher

The translations are extracted into language files (e.g. en.json for English) and then paraglide-js compiles them into helpers for use with the m-function-matcher. An example:

<SettingsPageHeader
   title={m.extensions_atx_power_control()}
   description={m.extensions_atx_power_control_description()}
/>

shakespere plug-in

If you enable the Sherlock plug-in, the localized text "tooltip" is shown in the VSCode editor after any localized text in the language you've selected for preview. In this image, it's the blue text at the end of the line :

Process

Localizing a UI

1. Locate a string that is visible to the end user on the client/browser

2. Assign that string a "key" that reflects the logical meaning of the string in snake-case (look at existing localizations for examples), for example if there's a string This is a test on the thing edit page it would be "thing_edit_this_is_a_test"

   "thing_edit_this_is_a_test": "This is a test",

3. Add the key and string to the en.json like this:

   • Note if the string has replacement parameters (line a user-entered name), the syntax for the localized string has { } around the replacement token (e.g. This is your name: {name}). An complex example:

   {m.mount_button_showing_results({
      from: indexOfFirstFile + 1,
      to: Math.min(indexOfLastFile, onStorageFiles.length),
      total: onStorageFiles.length
   })}
   

4. Save the en.json file and execute npm run i18n to resort the language files, validate the translations, and create the m-functions

5. Edit the .tsx file and replace the string with the calls to the new m-function which will be the key-string you chose in snake-case. For example This is a test in thing edit page turns into m.thing_edit_this_is_a_test()

   • Note if the string has a replacement token, supply that to the m-function, for example for the literal I will call you {name}, use m.profile_i_will_call_you({ name: edit.value })

6. When all your strings are extracted, run npm run i18n:machine-translate to get a first-stab at the translations for the other supported languages. Make sure you use an LLM (you can use aifiesta to use multiple LLMs) or a translator of some form to back-translate each new machine-generation in each language to ensure those terms translate reasonably.

Adding a new language

1. Get the ISO 3166-1 alpha-2 country code (for example AT for Austria)
2. Create a new file in the ui/localization/messages directory (example at.json)
3. Add the new country code to the ui/localizations/settings.json file in both the "locales" and the "languageTags" section (inlang and Sherlock aren't exactly current to each other, so we need it in both places).
4. That file also declares the baseLocale/sourceLanguageTag which is "en" because this project started out in English. Do NOT change that.
5. Run npm run i18n:machine-translate to do an initial pass at localizing all existing messages to the new language.
   • Note you will get an error DB has been closed, ignore that message, we're not using a database.
   • Note you likely will get errors while running this command due to rate limits and such (it uses anonymous Google Translate). Just keep running the command over and over... it'll translate a bunch each time until it says Machine translate complete

Other notes

• Run npm run i18n:validate to ensure that language files and settings are well-formed.
• Run npm run i18n:find-excess to look for extra keys in other language files that have been deleted from the master-list in en.json.
• Run npm run i18n:find-dupes to look for multiple keys in en.json that have the same translated value (this is normal)
• Run npm run i18n:find-unused to look for keys in en.json that are not referenced in the UI anywhere.
  • Note there are a few that are not currently used, only concern yourself with ones you obsoleted.
• Run npm run i18n:audit to do all the above checks.
• Using inlang CLI to support the npm commands.
• You can install the Sherlock VS Code extension in your devcontainer.

[Copilot]

Pull Request Overview

This PR introduces internationalization (i18n) support to the JetKVM UI using the inlang paraglide-js localization framework. The implementation enables multilingual support with translations for 9 languages and includes a comprehensive setup for managing localized strings throughout the React frontend.

• Added inlang paraglide-js as the localization framework with configuration for 9 languages (en, da, de, es, fr, it, nb, sv, zh)
• Replaced hardcoded UI strings with localized message functions across multiple components
• Updated build configuration and TypeScript paths to support the new localization structure

Reviewed Changes

Copilot reviewed 30 out of 31 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
ui/vite.config.ts	Added paraglide Vite plugin configuration for localization build integration
ui/tsconfig.json	Updated with new path aliases and compiler options for localization support
ui/tsconfig.node.json	Simplified configuration by removing redundant options
ui/package.json	Added inlang dependencies and updated scripts to include localization compilation
ui/src/ components and routes	Replaced hardcoded strings with localized message functions
ui/localization/	Added complete localization setup with message files for 9 languages
ui/index.html	Minor formatting and path corrections
ui/eslint.config.cjs	Updated import resolution mapping for new path aliases

Files not reviewed (1)

• ui/package-lock.json: Language not supported

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 89 out of 108 changed files in this pull request and generated 4 comments.

Files not reviewed (1)

• ui/package-lock.json: Language not supported

Comments suppressed due to low confidence (2)

ui/src/routes/devices.$id.tsx:1

• Corrected 'server' to 'serve' in comment"

import { lazy, useCallback, useEffect, useMemo, useRef, useState } from "react";

ui/src/hooks/hidRpc.ts:1

• [nitpick] Variable declaration moved inside the loop when it could be declared outside for better readability. Consider moving the offset calculation before the macroBinary creation."

import { hidKeyBufferSize, KeyboardLedState, KeysDownState } from "./stores";

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

Copilot reviewed 109 out of 126 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• ui/package-lock.json: Language not supported

Comments suppressed due to low confidence (2)

ui/src/hooks/hidRpc.ts:1

• Moving the offset calculation outside the loop and incrementing it manually could lead to incorrect offsets if the loop logic changes or if steps have variable sizes. The original approach of calculating offset = 6 + i * 9 was more robust and less error-prone.

import { hidKeyBufferSize, KeyboardLedState, KeysDownState } from "./stores";

ui/src/routes/devices.$id.mount.tsx:1

• The URL validation logic now runs in useEffect on every URL change, which could cause unnecessary re-renders. The original inline validation approach urlRef.current?.validity.valid was more efficient as it only checked validity when needed during render or form submission.

import { useCallback, useEffect, useMemo, useRef, useState } from "react";

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[IDisposable]

I've got the documentation created and all the remaining translations I missed (I think?) done.

[Copilot]

Pull Request Overview

Copilot reviewed 114 out of 132 changed files in this pull request and generated 6 comments.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[IDisposable]

Rebased to pull in the new sleep mode settings.