The ToDoList user interface can be translated into many languages. If you'd like to contribute to ToDoList and help others, this is a great way to do it! If you just want to use the software in your preferred language, you don't need to do any more than “Set Your Preferred Display Language”.

Users have contributed translations for languages shown to the left, and others. With each release of the software there may be new options and corrected text. The translation files need to be updated to keep up with these changes. This is done by volunteers around the world.

If you have questions please post them to our 'Translations' forum.

Go to menu>Tools>Preferences>General, and select from the drop-down list. If the language reads right-to-left, check the RTL option. (The video mentions a Add-To-Dictionary field. This was removed in v7.0.)

Once a file is selected and Preferences are saved, ToDoList must be restarted to use the new language. If you just want to use the software in your language, you can stop here - you're done!

• Set Your Preferred Display Language
• Location and Structure of Translation Files
• Editing Software
• Retrieving and Posting files
• YourLanguage.CSV
• New Translations
• Your Translation File
• Special Characters
• Clean Up
• Summary

Each language translation is stored in a .CSV file found under the install folder, in \Resources\Translations. Because there are regional dialects there can be more than one file for a given language. For example, there are differences in French and Spanish spoken around the world, and there are variations from north to south in both Germany and Italy. While it may not be “necessary” to have different files for each of these, the system allows for it.

In that folder is an icon file corresponding to each .CSV file. This is for a national flag or similar symbol as seen in the screenshots above. (The new standard icon format is PNG with transparency - no longer GIF.) The size is 16×16 @ 24BPP.

The first field of the first row includes the ToDoList version which applies to the file. For example: “TRANSTEXT 7.0.12.1”. The section “YourLanguage.CSV” has more information on this field.

The next row that starts with PRIMARY_LANGID is not used and can be ignored.

The next row has column headers for the three columns:

1. The English Text column has text to be translated.
2. The Translated Text is where specific translations are placed.
3. The Item Type column describes how the field is used (text, checkbox, label, etc). While it's not easy or recommended, this last field may be used to find the text in the software source code to ensure a context-appropriate translation. If in doubt, please post a question for Peter in the Google Group.

The rows are separated into two groups, NEED_TRANSLATION, and TRANSLATED. As an example of how this works, in the following image under NEED_TRANSLATION there are three rows with no Translated Text, followed by the TRANSLATED label, and that is followed by rows that have been translated.

Once the text in the first column is translated into the second column, the rows will automatically be moved down under TRANSLATED by ToDoList, as seen below. In this example, all text has been Translated, and there are no more rows that Need Translation. This “automatic” process requires a restart of ToDoList so that it will re-load and process the language file. If you are making changes to the language file, and ToDoList modifies that file, you may lose your updates! This could happen if your file is still open in an editor, or if there are errors in the file which cause the line movement to not work as expected. Get frequent backups. Copy your working file to another file after updates and before restarting ToDoList to modify them further.

When rows have similar text, translated words may be copied. However, for dialects and other specifics related to context, a simple copy/paste may not be appropriate. Please verify that translations make sense in each place where they are used.

In the above images you'll see “% Complete” followed by an indented “% Complete”. This is an indication that the second line is “probably” the same as the first. By default, indented lines will use the translation from the non-indented line above them. However, you should check the context for gender, number, subject/adjective/verb agreement, and other details to be sure. When text is followed by indented versions, only the first non-indented row must be translated. The subsequent rows will use the first value if they are left empty.

Microsoft Excel and other “spreadsheet” programs is good for viewing CSV files, but not for editing and saving. All data must be saved in UTF-8 (Unicode) format. The data must be tab-delimited, with quotes around all strings, and with paragraph markers at the end of each row. Microsoft Word and rich text editors are also not suitable for this kind of work, because they add unnecessary and potentially breaking characters into files. Programs recommended for this kind of editing include UltraEdit, Notepad++, and Sublime.

Whatever programs you use, never save with formatting, get frequent backups, and occasionally check to make sure that your file works within ToDoList (requires app re-start).

Be sure you have the most recent version of files before editing. The CSV and image files are loaded to your system with each new update. If you have modified your local files, after you edit a file, copy it to another folder so that it is not replaced in an update. An update will not overwrite a resource having a newer date than the equivalent file in the package. But there is a chance that someone else will submit language changes, their update will have a more recent date, and thus your file will get overwritten because now it's older than the file in the package.

Files can be downloaded from the GitHub Resources Repository. If you have a GitHub account you can fork the repo, make changes, push, then create a pull request. Or you can Edit with your browser or related tools. But if you are going to make several changes it will be better to modify your local files, test, then upload.

If you are not familiar with GitHub, this is a perfect opportunity to get started. But you can still download the files from the repo - individually or as a zip. To contribute your changes back, create a post in the Google Group, and attach your file there for review.

The latest GitHub files _should_ be rolled into each software update, but it's possible for them to be older or more recent than the files included with the software. The release has to be published before anyone knows there is a language change. So updates might/should be in GitHub before the very next update. To avoid these timing issues, before making changes to your files, and before reporting issues, check Github, check the installation folder, and check the forums to see if anyone has posted an update.

Whenever making changes to resources it would be helpful to post a forum note so that others know that files are being modified. This can help to avoid duplicate/wasted effort, and can help people to collaborate on changes. There are no comments in the language files, so unless a note is posted to a forum we may not know who is providing translations or how to contact them (you) with questions.

The name “YourLanguage” means this is a template file which gets copied to a new file named “whatever_your_language_is.CSV”. The file has all of the text that needs to be translated. There is no specific order to the rows. Some of them appear to be in alphabetical order but this is not consistent or required. There is nothing in the TRANSLATED section.

This file should never be modified by translators. Dan updates the file when the code changes and new translations are required.

The version in the first line/row (the TRANSTEXT row) is the last version ID where Dan changed this file. All translation files should be brought up to this release. Here is an example of the flow of translations from one release to the next:

1. Dan publishes a new YourLanguage.CSV along with prior files that need updates.
2. It's a good idea to announce in one of the web sites that you intend to make updates, to eliminate a duplication of effort or to find others for collaboration.
3. Kind volunteers like you submit updates.
4. There may be some discussion and revisions.
5. All updates are eventually posted to GitHub.
6. Dan publishes follow-up releases with the new files.

Again, because of possible timing situations, it's important for translators to get app updates and look for YourLanguage.CSV updates, see if others are working on translations, and check the GitHub repo and forums for updated files.

To create a completely new language file, copy the YourLanguage.csv template file to a new file, and name it as “language (region).csv”. For example: “Arabic (Egyptian).csv”

To create a dialect of an existing language file, copy the original .CSV file and change the region name. For example: “Arabic (Maghrebi).csv”, “Arabic (Sudanese).csv”, and “Arabic (Arabian Peninsula).csv”, and “Arabic (Levantine).csv”. Please only use English for filenames - this is a current restriction, not just a suggestion. For example, do not use “Français (Québécois)”, “Arabic (الدارجة)”, or “Arabic (العامية)”.

It may look like some of the lines to be translated are the same, but they are almost always not the same. The first field might only be different in capitalization, or with a trailing colon, or Special Characters (see below) like %d or \t.

All of these lines must be translated, with the punctuation and placeholders in the same _order_ as in the English version. The _position_ of special characters may be different between the English and translated versions, but the _order_ must have the same context. For example: “Downloading '%s' from '%s'” becomes “'%s' wird von '%s' heruntergeladen”
The software fills in the data in a specific _order_. The first %s is replaced with the current byte count and the second %s is replaced with the total byte count. It doesn't matter where the words are relevant to that as long as it makes sense at run-time.

If it's appropriate, copy translated words into each of the lines. But please be certain that the tense of the term does not change depending on the context. And where it's valid for the current language, please ensure capitalization is also consistent between the English version (first column) and your translated version (second column). For example: “%d% Completed:\t” becomes “%d% Komplita:\t” The special characters remain in the same position and the word remains capitalized.

However, note from the above example that because “Downloading” is no longer the first word in the translation, the translator made a decision to not capitalize that word. And in the above images you may notice that the translator did change the capitalisation and added a character, from “%Complete” to “%erledigt:”. While translators “should” be very careful to only translate exactly what is in the source field, you are welcome to employ “artistic license” to make small modifications if it improves readability.

In some cases an English term is used internationally, like HTML, RTF, PDF, or a brand name like “My Life Organized”. For such cases, if you leave the item untranslated the English term will be used. However, it's better to copy/paste the English text into the translated text, to be explicit and clear that you intend, for example, HTML to really be HTML in your language.

There are lines in the file used for opening and saving files. Change the description so that the meaning is clear to the user, but do not change the extension, since the same extensions are usually used globally. In the following example, the .dic file extension does not change to something like .wör: “Dictionaries (*.dic)” “Wörterbücher (*.dic)”

Similarly, where you see an elipsis “…” following text, leave that in the translation (in the appropriate location for RTL text). The elipsis is used as a visual cue in menus and elsewhere to indicate something else follows, perhaps sub-menus.

You need to re-start ToDoList whenever you want to check a translation, so you will probably want to make several changes before checking your work. Changes are available immediately after a restart.

If you don't see your change, it's possible that there are several places throughout the file where similar text needs to be translated, and you probably didn't get them all. As an example there are many lines with the text “Complete”, but some of them say “complete” and some are “% Complete”. The translation you provided may not be for the text you see in the app. Search the file, and if you're sure you got them all, post a note to the Google Group.

When you do see your changes, be sure the text fits within controls. If it doesn't consider using abbreviations, or post a forum note and explain the problem. Dan may suggest increasing the size of the field for all languages, or perhaps making dynamic changes based on the language or field.

As mentioned above there are many placeholders in the text like %s, %d, \n, and \t. These are replaced at run-time with live data. For example “%d% Complete” will result in “14% Complete”.

The order of the text and codes should only be changed if the context warrants it - for example if converting to a RTL language.

The \t is the internal code for a Tab character, and is often used to separate columns in a grid. For example, in a grid in ToDoList “AA\tBB” will put AA in column 1 and BB in column 2. In rare cases, like for the tooltip balloon that is displayed when hovering over a task, tabs are used to create two aligned columns of information. The number of tabs depends on the length of the words in the first column, and the length of the words depends on the language and usage of abbreviations. (*As seen in the image here, it looks like the English version should have “Status\t\t”…*)

The \n code is used for a new line. Again in a grid this might separate rows. In other text it's the equivalent of the Enter key. While this “should” never be changed. If translated text wraps around the screen abnormally, consider inserting a \n to break it into multiple lines. Always check to make sure such changes are correct!

Another special character is not a placeholder. The ampersand “&” is used indicate to a user that an Alt key is available to perform some function. For example, “&Help” is an instruction to the application to display an underline under the letter H so that the user knows they can get Help with Alt+H. However, if you are translating to another language where the word(s) for help are different like aider and aidez in French (similar in Italian and others), you can't simply change that to &Aidez-Moi because it will appear as Aidez-Moi, the user will use Alt+A, and get a completely different function. If you really need to change the keyboard shortcuts, consult with others who use ToDoList, those who do or will use your translations, and discuss the best way to approach the topic. Some won't care since they don't use shortcuts, others will already be using Alt+H for Aidez-Moi, and others may prefer re-defining Alt+A for help.

In Preferences next to the language selector there is a Clean Up button. Work in Progress. As of v7.0.12.1 The Clean Up button is not working. This will be fixed ASAP.

• When an update is available from Dan, the new YourLanguage.csv file will have changes.
• Click the Clean Up button to modify your active language file:
  • New lines are imported to the active language file under NEED_TRANSLATION.
  • Unused lines in the active language file are removed and saved into a file under \Resources\Translations\backups with a name like

“German (Germany).removed.2016-01-21_13-22-10.csv”

Now you can edit the language file and change the new lines under NEED_TRANSLATION. Save the file and restart ToDoList - this moves your translations under TRANSLATED. Check to make sure your changes are correct. Fix if required. Restart the application between each update. Post your changes back to the community.

If you are not modifying your language files then you don't need to do anything. The latest language files will come with software updates and they are already updated by others who follow these procedures.

To clarify:

• The Clean Up button causes synchronization between YourLanguage.CSV and the active language file. You only need to run this once for any language file that you use.
• Restarting ToDoList causes translated items to get moved to the TRANSLATED section.
• Both of these operations modify the language-specific files.
• Be sure that your modifications are saved to a backup file before Clean up and before restarting ToDoList.

Frequent checking of your work is highly recommended to ensure your translated text fits in screens and that you are getting the results you intended. Save and backup your files often to avoid chaos after investing a lot of time.

Sincere thanks go to anyone who participates in the translation project!