Skip to content
FUTO Notes

FUTO Notes languages and how to add a translation

FUTO Notes 1.8.0 is available in English and Simplified Chinese (简体中文). Every language lives in one JSON file in the app’s repository, and adding a valid file is the only change needed to add a language to desktop, iOS, and Android.

Change the app’s language

The app follows your system language by default. To pick one yourself:

  • Desktop (Linux, macOS, Windows): Settings → Language. The dropdown lists System first, then each language by its own name. The change applies immediately.
  • Android: Settings → Language, the same dropdown. On Android 13 and later it shares its setting with the per-app language in Android’s system settings, so a change in either place shows up in both.
  • iOS: Settings → Language → Open iOS Settings. iOS owns the choice there. iOS shows its per-app Language option only when your device has more than one preferred language in iOS Settings.

The language setting stays on the device. It does not sync, and it does not change your notes, filenames, search, or sort order.

How System picks a language

With System selected, the app walks your operating system’s list of preferred languages in order and uses the first one it has. A region variant maps to the language when there is only one sensible match: zh, zh-CN, and zh-SG all get Simplified Chinese, and en-US gets English. It never crosses scripts, so zh-TW and zh-Hant do not get Simplified Chinese; the app moves on to your next preferred language, and falls back to English.

What stays untranslated

Translations cover the app’s own interface: menus, settings, dialogs, errors, and editor controls. They do not touch note content, note titles, filenames, tags, or crash report contents. Text the operating system draws itself stays in the operating system’s language.

If a translation is missing a string, that string appears in English. A partly translated language is still offered in the list.

Add or improve a translation

Translations live in the languages/ folder of the app repository. languages/en.json is the source for every string, and languages/README.md is the full authoring guide.

  1. Copy en.json to a file named with the language’s BCP 47 tag, for example fr.json, pt-BR.json, or zh-Hant.json. To improve an existing translation, edit its file instead.
  2. Fill in the language block: englishName (used to sort the list), nativeName (shown in the dropdown), direction (ltr or rtl), and aliases (usually an empty list).
  3. Translate the values under messages. Keep the keys as they are.
  4. Run the checks from the repository root.

A new file needs this shape:

{
  "$schema": "./catalog.schema.json",
  "language": {
    "englishName": "French",
    "nativeName": "Français",
    "direction": "ltr",
    "aliases": []
  },
  "messages": {
    "settings": {
      "language": {
        "heading": "Langue",
        "systemOption": "Système"
      }
    }
  }
}

You do not have to translate everything at once. Anything you leave out falls back to English, and the language still shows up in the list.

Placeholders and plurals

Words in braces, like {noteTitle} or {count}, are filled in by the app. Keep them, and move them wherever your grammar needs them. You may leave one out, but you may not add a placeholder that the English string doesn’t have. To show a literal brace, write {{ or }}.

A message that depends on a number has a plural key and a variants object:

"count": {
  "plural": "count",
  "variants": {
    "=0": "No notes",
    "one": "{count} note",
    "other": "{count} notes"
  }
}

Use the CLDR plural categories your language needs: zero, one, two, few, many, and other. other is always required. Exact matches such as =0 are checked first.

Messages are plain text. No HTML, no markdown, and no leading or trailing spaces.

Check your file

Run the language checks from the repository root:

pnpm install
pnpm run check:languages   # must pass: file names, structure, placeholders, plurals
pnpm run audit:languages   # optional: lists missing, extra, and possibly stale strings

The checks need Node and pnpm; see Build FUTO Notes from source for the versions.

check:languages reports every problem in every file at once, with the file name, the message path, and the reason. audit:languages is informational and does not block anything.

To see the translation in the app, run a development build with just tauri-dev and pick your language in Settings → Language. The build finds new files on its own; there is no list of languages to update.

Right-to-left languages

Set direction to rtl and the app mirrors its interface for that language. Your notes keep their own text direction.

Send a translation upstream

To offer a translation, open an issue on the public tracker at github.com/futo-org/futo-notes/issues. The project has not published a process for outside translation contributions yet. The terms for modifying and sharing the source are covered on FUTO Notes license.

Next steps