Translation How-To

This page will give you all the information you need to translate Freeplane into your own language.

Freeplane GUI translation and improvement

This How-To section describes the tools and (alternative) processes for Freeplane GUI translation. This concerns the translation of all the English source strings displayed in the Freeplane interface, especially in menus and dialogs.

English is the source language for all translations, so you need to know English to be a translator.

UI designers need to be able to improve the UI by improving the existing English source strings and by adding new tool tips. Since they use the same tools and almost the same processes, these processes are also described here.

This How-To uses the following conventions and terms:

• Language code: 'xx' in any file name or URL means the two letter language code of the language you are translating to. So you have to replace it by that language code to make it work.
• Your language page: https://hosted.weblate.org/projects/freeplane/translation/xx/, Weblate page that gives an overview of the translation of Freeplane to your language. For details see Weblate
• Your translation item: An untranslated English source string that you would like to translate or an existing translation that you would like to improve.
• Translate page: Weblate page where you can edit your translation item, see How to translate
• Translation key: This is a unique text string that links a certain English source string to all its translations and defines the location where the source string or its translation is displayed in the user interface.
• File separator: '/' (forward slash) is used as file separator in the display of paths in order to be compatible with all relevant operating systems. '\' (backward slash) is the default in Windows, but '/' will work as well.
• Freeplane user directory: <fpuserdir> preceding any file name is the path to the Freeplane user directory. This path ends in /Freeplane/1.5.x/ where the last subdirectory varies between major releases. You can open this directory in your file manager via the Freeplane menu Tools > Open user directory.

Tools: Weblate and (soon to come) Freeplane translation editor

Weblate

Since version 1.3.x Freeplane uses a collaborative web based translation tool developed by Michal Čihař. For all described processes the translations are entered or imported in Weblate (except for new tool tips which are merged directly into git). From Weblate all new and changed are committed to the Freeplane git release branch. Weblate stays in sync with the Freeplane git release branche, so any committed new tool tip or other new translation key and its English source string are immediately available for translation in Weblate. With every new Freeplane release the current state of the Freeplane translation in Weblate is also released.

In order to get started as a Freeplane translator or UI designer in Weblate you need to know and do a few things:

• You can find the Freeplane Weblate project page here: http://hosted.weblate.org/projects/freeplane.
• If you have not registered for Weblate yet, you need to do so by clicking 'Register' in the top-right corner and following the instructions.
• It is important that you know how to find your language page, i.e. the Freeplane Weblate page that gives an overview of the translation to your language, has some handy filters for strings to check and has the menu items Search and Files that we are going to use in this How-To:
  • On the Freeplane Weblate project page, click component Translation and then on your language
  • If in your Weblate profile you specify your translated language and subscribe to the Freeplane project, a link to this page appears in your Weblate Dashboard
  • The web address of this page is https://hosted.weblate.org/projects/freeplane/translation/xx/ where 'xx' is the 2-letter code for your language.
• You need to get yourself familiar with Weblate functionality, so take a look at the Weblate translator guide and keep it as a reference next to this How-To.

If you find bugs on the Weblate tool, you can report them here.

Freeplane translation editor (soon to come)

The Freeplane translation editor is a tool for translators and UI designers that is available in the Freeplane GUI. It appears when you press Crtr+Shift+F10 while your mouse is hovering above the text of your translation item. It shows a translation window for the text string and, if applicable, for the tool tip associated with the text string. You can choose to do one of 2 things:

• You can choose to translate in the translation window itself (i.e. offline translation). When you close Freeplane, all translated items are stored in a local file: <fpuserdir>UserResources_xx.properties, that can be uploaded to Weblate.
• Or you can choose to press the Weblate button. This takes you straight to the correct translate page, the Weblate page where you can edit your translation item.

The translation editor does not work for all GUI text strings. In that case the message "No translateable string found" appears in the bottom-left corner of the Freeplane Window.

For some tool tip items you might notice that offline editing is disabled and that the translate page cannot be found. In that case it is a new tool tip.

Online or offline translation?

In the following 2 paragraphs it is explained in detail how these 2 tools work together in online or offline translation. Both ways have advantages over the other.

Online translation	Offline translation
Easy to collaborate	Fast
Automatically work on the most current translation	You immediately can check the result of your translation in the Freeplane UI
More information and tools to support translation: glossary, machine translation, review flags, comments, history	You do not need Internet during translation

When to use online or offline translation depends on what you have to do, your circumstances, your translation skills and the preferences of you and your co-translators. Here are a few examples

Online translation	Offline translation
When you have to improve existing translations	When you have to translate untranslated items
When you translate a few items from time to time	When you want to and are able to translate a lot of items in a short time
When you need to collaborate with other translators for your language	When you are the only translator for a language
When machine translation and a secondary language can help you translate	When you are able to translate without any aids
When the quality of translation is more important	When the speed of translation is more important
When you always have access to Internet	When you need to be able to do part of the work offline

Online translation

Online translation has basically 3 steps:

1. You need to find, filter and/or review translation items
2. Translate an item
3. Test your Weblate translation

How to find, filter and/or review translation items

The following 4 scenarios can help you to get from no translation to a complete and improved translation. You could use a combination of scenario 1 and 2 to go through all menu's and screens systematically followed by scenario 3. Scenario 1 is the only scenario that can be replaced with offline translation. Scenario 4 can take place at any time. In case of a largely completed translation that needs maintenance, the scenarios can be used in any order. New tool tips and other new English source strings and translation keys that are added during development are probably easiest found through scenario 3, though it might be difficult to find the location of these strings in the user interface.

Scenario 1: In the Freeplane user interface you see a string you would like to translate or improve and you can use the Freeplane translation editor. You can recognise untranslated strings as the English source string with the token [Translate me] attached to it. Otherwise you could see a string that needs better formulation or correction of a language error. Hold your mouse above the intended string and press Ctrl+Shift+F10 to invoke the Freeplane translation editor. It will show the string and, if applicable, its tool tip. Press the Weblate button of the string you would like to translate or improve. That will directly open your web browser with the Weblate page for your translation item. In a few cases this scenario does not work or stops here:

• When you press Ctrl+Shift+F10 the translation editor does not appear and the message "No translateable string found" appears in the bottom-left corner of the Freeplane Window. The translation editor cannot handle this type of string and you should use scenario 2 to find and translate this string.
• After you press the Weblate button, the translation item cannot be found in Weblate. This concerns a new tool tip, see New tool tips
• You may find that the string is already translated or improved. This is because Weblate can be ahead of the translation that came with the Freeplane release you are using.

Scenario 2: As scenario 1 but without the Freeplane translation editor. Once you have identified your translation item you go to your language page (https://hosted.weblate.org/projects/freeplane/translation/xx/) and press Search. In case of translation you enter the English source string in Query and enable option "Search in source strings" In case of an improvement you enter the current translation in Query and enable option "Search in target strings". After pressing the Search button you might directly find the page for your translation item. If you find more than one item, you can browse through them to find your translation item. If you find nothing or the wrong item the English source text or the translated text has been changed in Weblate since the moment of the Freeplane release you are using. You can try to find them by reducing the number of keywords in the search.

Scenario 3: Finding remaining or new untranslated items in Weblate. In Weblate you can easily find all untranslated items by clicking 'Not translated strings' on your language page. Disadvantage over scenario 1 and 2 is that you might have difficulties to find the location of these translation items in the Freeplane interface, so you miss the context that helps you to translate or improve it. After having gone systematically through all menu's and screens with scenario 1 and 2, this is the only way to find the remaining untranslated items.

Scenario 4: Reviewing translations. In scenario 1 and 2 you review the translations directly in the Freeplane interface. In Weblate there are many additional ways to select translations for review:

• Review all translation items marked for review: Click the link 'Strings marked for review' from your language page. You can now browse through all translations that are marked for review by other translators or automatically by Weblate if the English source string has changed. If necessary you can improve the translation. If your are satisfied with the translation, remove the tick "Needs review" and save.
• Review all translations done by other translators since a certain date: From your language page click Search, in the Review pane specify the date and click "Start review".
• Review consistent translation of a certain keyword: From your language page click search, enter the keyword, only enable "Search in source strings" and hit the Search button.
• Review translations with failed checks: From your language page click the link "Strings with failed checks". On the search page you can use "Search filter" to filter on specific failed checks.

How to translate

The basis of the translate page is the English source string and the translation field. For an untranslated item you can enter the translation. An existing translation you can review and change. You can also enable or disable 'Needs review' if necessary. Then you can save your changes.

How to test your Weblate translations:

• Open your language page: https://hosted.weblate.org/projects/freeplane/translation/xx/
• Choose Files
• Click "Download", save freeplane-translation-xx.properties
• Copy freeplane-translation-xx.properties to <fpuserdir>resources/translations/Resources_xx.properties
• Restart Freeplane
• Test your translations
• Close Freeplane
• Remove <fpuserdir>resources/translations/Resources_xx.properties, otherwise it will overrule newer translations that will come with new Freeplane releases.

New tool tips (soon to come)

The translator editor has also functionality for UI Designers to add new tool tips in order to improve the user interface. Translators can recognise these new tool tips by the fact that the entry field in translator editor is disabled or by the fact the Weblate button does not find the translation item. A translator can enable the translation of a tool tip by taking over the role of the UI designer. It requires the translator to submit an English source string before the actual translation can start. It also requires an developer to add the new translation key and source string to Weblate, so enabling is not an instant action. The next paragraphs describe in detail the different processes with regard to new tool tips.

UI designer process

This process is for new tool tips only. If you want to improve the source string of existing tool tips follow the regular process to change source strings.

1. Check if there is any open "New tool tips" bug report. If so, wait till they are all closed and Weblate is up to date. If not, you might repeat your own work or overwrite your co-designers work.
2. If the Freeplane language is other than English, change it to English in Preferences
3. Close Freeplane
4. Remove <fpuserdir>UserResources_en.properties to prevent submitting the same new tool tips
5. Download the English source through menu "Files > Download original translation file (Java Properties(ISO-8859-1))" from https://hosted.weblate.org/projects/freeplane/translation/en/. Save it as <fpuserdir>viewer-resources/translations/Resources_en.properties. In this way your local source strings are up to date.
6. Start Freeplane
7. Hover over the item that you would like to add a tool tip to. If there is already a tool tip, skip the item. If not, press Ctrl+Shift+F10
8. Enter the text for the tool tip (the bottom field) and press OK.
9. Repeat the last 2 steps till you have finished what you had planned
10. Close Freeplane
11. Create a new bug report titled "New tool tips" and attach <fpuserdir>UserResources_en.properties
12. If necessary, change Freeplane back to the original language.

Translator process

If you want to enable translation for a certain tool tip, you should follow the following steps.

1. Hover over the item with the disabled tool tip and press Ctrl+Shift+F10.
2. Press the Weblate button. If the translation key is present in Weblate, you can continue with normal online translation. For the offline translation process continue with that section below. If no translation key is present, continue with the next step
3. Follow the steps of the UI designer process
4. When the "New tool tips" bug report is closed, continue with online translation. For offline translation process continue with that section below.

Offline translation process for new tool tips

This is the same as the normal offline translation process, except that you need to update the English source strings to enable the new tool tip fields:

• Download the English source through menu "Files > Download original translation file (Java Properties(ISO-8859-1))" from https://hosted.weblate.org/projects/freeplane/translation/en/. Save it as <fpuserdir>viewer-resources/translations/Resources_en.properties. In this way your local source strings are up to date.

Collaborate to translate to your native language

Communication through the Freeplane

If you feel the need to discuss translations to your native tongue you can do so in your native language on the forum. Always search if there is already a thread for your language. Here is is an incomplete list of forum threads and pages related to the translation to different languages.

French / Français

You can have a look at:

• Old forum thread 1

• Old forum thread 2.

Flemish/Dutch / Nederlands/Vlaams

• You can consult Translation nl for general guidelines

• Your can post your questions, remarks and requests in this thread

• This is an old thread on Dutch documentation

Frequently Asked Questions / Tips for translators

While running Freeplane, why are some strings ending with "[translate me]"? 

As long as a key is missing in a translation, Freeplane automatically uses "<English text> [translate me]" as translation. Translators should translate these strings in priority and then remove "[translate me]".

Why are strings ending with "[auto]"? 

Translation files can be submitted to an automatic translation tool, then strings of type "<English text> [translate me]" becomes strings of type "<local language text> [auto]". Translators should search and review these strings and then remove "[auto]".

Why is there sometimes space before values? 

spaces before values are ignored, don't care.

Why is there & character before some values (sometimes "in" the words)? 

the ampersand (&) is used to mark keys in the menu (i.e. open the menu, press the key/letter to activate the menu entry) - while translating, you need to make sure that each letter is only used once per menu.

Some values begins by <html> with no </html> at the end? 

Java accepts unclosed tags - don't care.

Some keys are not used / displayed in the software 

you should stay aligned with the English version to be on the safe side, but if keys are not used, it's a bug you can report it here.

When testing Freeplane with my translation file, some menus are missing or some buttons have no label, why? 

If you leave any empty keys in the file, Freeplane assumes they are valid translations and displays nothing. There are differences between "empty key in the translation file" which displays nothing and "missing key in the translation file" which displays "<English text> [translate me]" (see above).

Your translation is truncated 

If your translation is truncated when displayed, it may contains a ' (apostrophe) character (e.g. Freeplane displays "Copier l" instead of "Copier l'identifiant"), you may simply enter the ' character twice (ie "Copier l"identifiant") as translation, where " is twice the character '. Most of the time, ' apostrophe characters should be handled as in the English version (for some strings which are used in format statements put them twice, for other strings put them once).

Translation of Freeplane add-ons

Add-ons manage their translations on their own, i.e. the translations are integrated into the add-on sources. Nevertheless, it's simple to translate an add-on by editing the add-on installation package in Freeplane and modifying the translations therein. If the translations contain non-ASCII characters you have to encode the text using a script, either from the Developer Tools (since version 0.9.16) or from here.

Translation of third party tool used in Freeplane

JOrtho spell checker

For spell check Freeplane relies on JOrtho project. JOrtho translation file contains very few strings and only 5 are used in Freeplane but if you want to translate this file too, you can get it at its current location.

Translation of Tutorial or Documentation maps

These are the mind maps you get when you press Help → Tutorial (freeplaneTutorial.mm) and Help → Documentation (freeplane.mm).

Basic steps

1. Create a working directory myTranslations.
2. Copy the most recent English documentation from http://freeplane.sourceforge.net/mapsOnline. For this choose Help > Documentation Maps Online and select the map of your choice; or copy your last translation.
3. make a subdirecory structure for images: myTranslations/doc; (if you use these, also myTranslations/mouse and myTranslations/key).
4. Copy images you reuse or put new images you use in myTranslations.doc (possibly also myTranslations/mouse and myTranslations/key).
5. Edit your translation. Drag your images from the defined subdirectories into your translation (assuming URI's are relative).
6. Test the translation, in particular the images.
7. Zip directory myTranslations.
8. Select Help > report a bug, select new report of type translation and upload the zip file.

Note Check Help > Documentation Maps Online > indexMap > Images/doc for the images used in the present doc mind maps.

Old

1. Download the latest version of freeplane.mm and FP_MenuReference.mm (or an already existing versions in your language) from the repository.
   • The current link is https://github.com/freeplane/freeplane/tree/master/freeplane/resources/translations/ (but check if it's not an outdated link)
2. Visit pages http://freeplane.sourceforge.net/doc/freeplane_all_languages.html and http://freeplane.sourceforge.net/doc/FP_MenuReference_all_languages.html to see how the documentation is automaticly translated by Google Translate.
3. Using the latest development version of Freeplane, just create a map in your language (or complete the one already existing).
   • As it's almost impossible to track differences between maps and ensure an exact one to one relationship between the languages, we don't expect this from translators.
   • To track changes of freeplane.mm filters can be useful: Open the file in normal mindmap mode (not via F1) and apply a "Date filter" with the modification time set to the last time you have edited the translated map.
   • Just make sure that the map is consistent with the current version of Freeplane, as complete as possible and helpful to users.
4. Go to the tracker (requires Sourceforge log-in) and upload your map (the Project should be set to Translations).

Keys Mapping translation

TBD

Java Help translation

TBD (the current version doesn't allow for localization). Hint for later: http://jhelpdev.sourceforge.net/