Skip to content

Translation

Jump to bottom
David Lynch edited this page Oct 18, 2026 · 2 revisions

Contributing translations

Thank you for helping to translate these addons. You do not need to know how to program: a translation is one text file with a list of "English text = your text" lines.

What needs translating

The addons have two kinds of text, and they live in different places:

Kind Examples Where it lives
Interface text Option names, menu items, tooltip lines such as "Hide this point" The shared handler repository. One translation file here serves every HandyNotes addon that uses the handler.
Notes and labels "Pick up the torch, and find three keys in the village" The repository of each addon.

You do not need to translate names of creatures, items, spells, zones, or achievements. The game already shows these in your language. They appear in the text as markers, for example {npc:258938}, and the addon replaces each marker with the name from the game.

Language codes

A translation file is named for the game's language code:

deDE, esES, esMX, frFR, itIT, koKR, ptBR, ruRU, zhCN, zhTW

English is the source language (enUS) and needs no file. Clients that use British English report enUS.

The file format

Each file is a short Lua file. This example is locale/frFR.lua:

if GetLocale() ~= "frFR" then return end
local _, ns = ...

ns.AddTranslations("frFR", {
    ["Fly as high as you can"] = "Volez aussi haut que possible",
    ["Hide this point"] = "Masquer ce point",
    ["Hide %s only in %s"] = "Masquer %s uniquement dans %s",
    ["Wanders the camp a bit"] = "",
})
  • The text on the left is the English text. Do not change it. It must match the addon's text exactly, because the addon finds your translation with it.
  • The text on the right is your translation.
  • An entry with "" on the right is ignored, and the addon shows the English text. You can translate a file a little at a time.
  • If the English text in the addon changes, the old translation no longer matches. The addon shows the English text until the entry is updated. This is safe, but it means translations need small updates from time to time.
  • A double quote inside the text is written \". A new line is written \n. Copy these from the English text.

Special markers in the text

Some English text has markers. Keep them exactly as they are.

  • {npc:258938}, {item:1234}, {spell:5678}, {area:16204}, {achievement:1234}: The game replaces each marker with a name, and sometimes an icon. You can move a marker to wherever it fits in your sentence. Do not translate the marker, and do not remove it.

    "Talk to {npc:258938}, then pick up {npc:261115}." "Parlez à {npc:258938}, puis prenez {npc:261115}."

  • {gc:red:You cannot mount up}: This shows the text in a color. Translate only the text after the second colon. Keep gc and the color name.

    {gc:red:Vous ne pouvez pas monter en selle}

  • %s and %d: The addon puts a name or number here. Keep them. If your language needs a different order, use %1$s for the first item and %2$s for the second:

    ["Hide %s only in %s"] = "In %2$s, hide %1$s"

Interface text (the handler)

The English interface text is every L["…"] in the handler's Lua files. To list them, run this in a copy of the repository:

grep -rhoP 'L\["(?:[^"\\]|\\.)*"\]' --include=*.lua . | sort -u

Copy locale/frFR.lua as a starting point, rename it to your language code, and change the two language codes inside it. Then add a line for your file to handler.xml, after the line for locale\frFR.lua.

Notes and labels (an addon)

Each addon can list its own text for you from inside the game.

  1. Log in and type the addon's key command. The command is the addon name without HandyNotes_, in lower case, followed by keys. For HandyNotes_MidnightTreasures, type /midnighttreasureskeys.
  2. A window opens with the text already selected. Press Ctrl+C to copy it.
  3. Paste it into a new file locale/<your code>.lua in the addon. Change xxXX to your language code on the two lines where it appears.
  4. Fill in the right-hand side of the entries.
  5. Add a line locale\<your code>.lua to the addon's .toc file, below the line for the existing locale files.

If your game client is already in your language and the addon already has some translations for it, the window fills those in for you. Then you only need to translate the empty entries. A translation that no longer matches any text in the addon is not listed, so it is dropped from the new file.

Checking your work

The addon only loads translations for the language the game client runs in. There are two ways to look at your work:

  • Run the game in your language, type /reload after each change, and look at the text.
  • To check on an English client, change the language code to enUS in both places in your file (the first line and ns.AddTranslations), then type /reload. Change it back before you send the file.

If an entry has no effect, check that the left-hand side matches the English text exactly. A missing space or a different quote mark is enough to stop it matching.

Sending your translation

Open a pull request on GitHub.

  • Interface text goes to the handler repository: the new locale/<code>.lua and its line in handler.xml.
  • Notes and labels go to the repository of the addon: the new locale/<code>.lua and its line in the .toc.

You can also open an issue with the file attached if you do not use pull requests. Please tell us if some of the translation is a guess. It is better to leave an entry blank than to send a wrong one.

Clone this wiki locally