Important: If you haven’t done so already, make sure to first read the Getting Started with Localising Agenda introduction. Also, this topic assumes you have previously volunteered as a translator on one of the language pages and that you have received from us the invite to the Crowdin web application, as well created an account that allows you to log in.
Overview of the Crowdin interface
Translating Agenda is done through the Crowdin web platform. When you enter your account details the main window will load the list of languages you have access to. If you select your language you will see a list of files that need to be translated:
The easiest is to just click on Translate All and you will see all translatable phrases:
On the left you will see a list with the individual translatable items. At the top you’ll find both a search field as well as options that allows you to filter on those items that still need work or need updating:
The details for each item shows on the right the original English phrase/word, and optionally (but importantly!) a comment or description explaining in more detail where/how the word is used:
The comment can also look a bit cryptic like below, in which case it has been auto-generated from interface files and usually means it’s one of the menu items in Agenda.
Directly below to the English original phrase/word, you’ll find the area where you should enter the translation in your language. Below these buttons is shown who has made and verified the translation, etc. It will also show alerts if for example the original phrase has changed and how.
Note how Crowdin also suggests matches you have used in the past already, as well as TextMining suggestions using DeepL.
Finally, there’s an area on the right where translators and reviewers can leave comments, for instance to ask question, make suggestions, explain rationale etc:
Tip: Check out the following tutorials on the CrowdIn website for more details on how the app works both as a translator and as a reviews:
First round
We suggest to do the translation to your favourite language in two steps, starting with 2-3 people doing a first round to complete an initial translation, before in a second round others join to review and test.
Tip: Each time we add a reviewer, she/he is added to an agenda.community message, which you can also use to coordinate with each other which approach to take, who does what etc. Likewise the Crowdin app itself also has extensive commenting and communication possibilities you can make use of, which ever way works.
The list itself can be divided in two parts:
Initial translations
The largest amount of work is to go through the list for the initial translation. Note that you can use keyboard shortcuts to copy the source phrase to the translation field, which can be useful as a starting point. Once you have filled in a translation you can mark it as translated, using the ⌘-Return shortcut if you want. It will automatically jump to the next item (you can also jump between items using the tab and shift-tab shortcut).
After round one all entries should have a translation, after which ideally someone else (second pair of eyes) should approve the translation.
Note: on the overview page with the files for your language you can see if all sentences have been translated. The percentage indicator shows which files still need to be translated. Red indicates phrases not yet translated, blue indicates phrases that have been translated but not yet approved, and green means you’re done
Sharing the pain
Providing all the translations can easily be some hours of work, and it makes sense to divide and conquer, for example by agreeing that one starts at the bottom and the other at the top of the list. Make sure you coordinate from which point everybody starts.
Important: If you divide the work with multiple translators, make sure that 1) each of you have gone through the the already completed translations so you have seen the standard vocabulary, 2) that once you hit the point where the other has already provided a translation, you continue reviewing those to identify potential inconsistent uses of actions and verbs that need updating. First establishing which are the key verbs and nouns you will use (see next item) is also a good idea that can save a lot of work later.
Choosing the right vocabulary
A great translation is one that is consistent and uses the same and correct vocabulary everywhere. Here are some tips on how to achieve this:
Appname
In principle the Agenda app name should not be translated and be kept Agenda. The exception is the Dutch language version that is called Agendanotities because the Calendar app is already called Agenda on Dutch systems. If there are strong arguments to be made about adapting the Agenda app name for your language please discuss this with us first.
Basic actions and nouns
It’s good to decide on the basic actions and nouns first, for instance by reviewing the English translations it’s quite obvious which terms appear frequently. Think for example about:
- Category, Project, Note, Overview
- Calendar, Event, Reminder, Date
- Linking an Event, Assigning a Date
- Collapse/Expand, Pinning a note
- Premium features, Purchasing
When deciding on the term for Premium features please note that we prefer to have the focus on the functions giving you more advanced/pro capabilities rather than focusing on the fact you have to pay for them.
Tip: For an example of how to approach this, have a look at the French localization page and how they approached things.
What do Apple’s apps do
Another thing that might be useful is to check how Apple has approached things in some of their apps, for instance in:
- Finder, when it comes to file handling, quicklook, folders, etc
- Notes, TextEdit, and Pages, when it comes to notes, formatting and text styling, exporting, etc
- Reminders and Calendar, when it comes to reminders and events
- System Preferences/Settings.app, when it comes to appearance, iCloud and other settings
Tip: If you would like to run a specific app like Apple Notes in a different language then the one your system is in, have a look at this trick. For example in order to run the Notes app in German you would start it through the terminal using this command:
§ open -a /Applications/Notes.app --args -AppleLanguages '(de)'and like this you run Safari in French:
§ open -a /Applications/Safari.app --args -AppleLanguages '(fr)'
Google Translate
Another great help, especially when it comes to translating the sample documents, is to use the built in TextMining suggestions (or use the tool of your preference in a separate window of course):
It can often be a great starting point, however it almost always needs tweaking. Make sure to go over the result and tweak things to make it more natural sounding, but also to ensure you pick the right sayings and expressions (which are often a bit different than the literal translated words from English), and the right verbs have been used (for example where the word “Ship” in English can mean a boat but also the verb to send something). Google translate is great but it’s not perfect.
Important: make sure that Google translate doesn’t change things like quotes, or em-dashes (see for example the “– I’m so excited!!!” part in the screenshot above), spacing, returns, etc. This also goes for placeholders (see below)
Tip: be careful with some translations coming from Google Scholar or other platforms as often it suggests terminology from the Android platform, which can be subtly different sometimes.
Plural forms
Some phrases can have both a singular and one or more (depending on the language) plural forms:
Note that if you completed only one of the forms the phrase will have a yellow instead of a green square in front, indicating that one or more forms are still missing.
Placeholders
Some sentences can contain so-called placeholders, where Agenda fills in things like numbers or names.
These appear in a few different forms:
%@which is replaced by another piece of text, like in “Delete note with title %@?”%dwhich is replaced by a number, like in “Do you want to delete %d projects?”%1$#@count@which is replaced by another piece of text, like in “Unpin %1$#@count@ from the top?”, which will end up as “Unpin 2 notes from the top?”.
It’s very important that you keep the placeholder as they are, that is, they should be present in the translation the same way. They can however be placed where it makes sense for your language, for example:
- English: “Delete note with title %@?”
- Dutch: “Notitie met titel %@ verwijderen?”
Some placeholders can also have an associated number with them, in case multiple placeholders appear in the same sentence:
Again, make sure to keep the placeholders as they are, but also make sure that all placeholders appear in the translated sentence. You can however change the order as you see fit for your language, for example:
- English: “Now, ends %1$@, %2$@” => Now, ends tomorrow, 3pm
could also be translated as:
- Dutch: “Nu, eindigt om %2$@, %1$@” => Nu, eindigt om 3pm, tomorrow_
In general though, try to stick as close to the original translation as possible. Note though that in this example we don’t start the sentence with a capital as that’s more appropriate in Dutch.
Another type of “placeholders” you will encounter are html <b> and </b> tags in the sentences used in the opening movie. You should use these in the translation as well but you can place them where they make most sense.
Spaces and Returns
The same goes for spaces and returns, which are also important to keep as much as possible close to the English original. For instance, if the English sentence is " , and", also the Dutch " en", starts with a space.
Similarly, in some sentences you’ll find character returns, these are on purpose and should be maintained. The same goes for punctuation like a sentence having or not having a period at the end. The can however be tweaked to make things look or work better in a later stage (see below).
Dates and Time units
In order to display time and date intervals we ask you to translate the various date units like hour, minute, seconds, day, week, month, and year in three formats (full, abbreviated, and compact). You can see which one is asked based on the key for the phrase:
If the key contains “Full” like in it time.unitYearFull, it means the fully written unit:
- 1 year, 3 months, 2 days
- 3 hours, 2 minutes, 20 seconds
If the key contains “Abbreviated” like in it time.unitYearAbbreviated, it would be the next smaller way of saying:
- 1 yr, 3 mths, 2 days
- 3 hrs, 2 min, 20 sec
Finally, if the key contains “Compact” like in it time.unitYearCompact, we are looking for the smallest possible way of saying:
- 1y 3m 2d
- 3h 2m 20s
Relative Dates
We often refer to days in the recent past or upcoming future in a relative way, for instance as last Sunday or coming Wednesday. What we found is that there can be a bit ambiguity around what to use when, there’s no real standard, most people have their own interpretation depending on how far away the days are. But to give some insights, here is what we do in terms of the “algorithm”, which might help picking what makes most sense:
assuming it’s currently wednesday
- If day X is more than 7 days ago :
- full date (2 may 2020)
- If day X is less than 7 days ago :
- if it was yesterday => yesterday
- if the day still falls within the same week (e.g. monday before the wednesday), => just the day name (Monday) in English and Chinese, last Monday in all other languages.
- if the day falls in the week before (e.g. friday before the wednesday), => last friday
- If day X is less than 7 days in the future :
- if it is tomorrow => tomorrow
- if the day still falls within the same (current) week (e.g. friday after the wednesday), => this friday
- if the day falls in the next week (e.g. monday after the wednesday), => coming wednesday
- If day X is more than 7 days in the future :
- full date (2 jun 2020)
Because of the ambiguity you can have a lot of discussion about this, but we’ve settled on the above. Best to pick the words you feel fits best with this schedule. For instance in Dutch:
- last tueday => afgelopen dinsdag
- this tuesday => aanstaande dinsdag
- coming tuesday => aankomende dinsdag
The difference of aanstaande vs aankomende is pretty minimal actually, but aanstaande feels a bit more “imminent” then aankomende.
First build to test
Once this first round has been completed we ask you to let us know and we can start the second phase by 1) inviting the other volunteers to review the translations, and 2) by creating a test build for all of you to check. Here are some of the things to have a look at:
Review of translations
Make sure to go over all the translations in the Crowdin project. Is everything translated and marked as approved? Is the right capitalisation used? Are the translations consistent (same verb and noun)? Are the placeholders used correctly? Are spaces, returns and punctuation correct?
Comments and suggestions are often best left in the comments section on the right, along with marking the translation as needs revision so it can easily be picked up by others as needing attention.
At the same time, also use the test build of the app to verify whether in practise the translations work nicely:
Layout
Are all phrases and sentences shown? Was anything missed or misinterpreted? Are none of the buttons, labels, etc, clipped instead of shown in full? These kind of issues are usually easiest communicated through the page on the community for your language.
Does everything work
Functionally the app should also be checked, for instanced if due tags are still working, if calendars and dates are shown correctly and work as expected according to the region and locale settings your system is in.
Tip: If you normally run your system in either English or a different language than the one you’re helping to translate, this article explains how you can run Agenda in a different language than your system uses.
Welcome tour and Preferences
Also make sure the first run experience works as expected. On macOS this can be checked easiest by choosing Help > Welcome Tour from the main menu, while on iOS and iPadOS the same option can be found by going to the Agenda Preferences > Help & Support > Welcome Tour. Speaking of which, also make sure the preferences and other items like popovers, date pickers, and menus are properly translated and working.
Things to tweak
While in general we suggest to stay as close as possible to the original English version of Agenda, there are a number of areas where it might make sense to deliberately do things differently.
Capitalization
A good example is capitalisation. On English systems Apple uses a kind of camel-case flavor when it comes to menu item commands, e.g. “Save Search as Overview”, while on a Dutch system this is not the case: “Bewaar als overview”. The same goes for things like the name of the weekday being capitalised (e.g. Wednesday in English) or not (e.g. woensdag in Dutch). In these case we suggest to follow what Apple does (see above).
Layout
Another area where you might need to deviate is in places like button titles or labels where space is limited. For example in English we might use Contact Support as the button title in an error dialog, while in Dutch we used Contact opnemen (only the verb) because Contact met ons opnemen would be way to long for a button.
Features
The features section can also require some deviations from English as it only allows for limited space, for example note how in Dutch we didn’t translate the “turning them into footnotes” part in the description:
Sample documents
The sample documents need a bit of creativity as well in order to preserve both the storyline as well as making sure the humor, sayings, and names work also in your language. For example, in Dutch we decided to change the name of Janice, which is not a very common name, to Janiene. Similary we changed High Tea, Inc. to High Tea B.V. the abbreviation for a limited liability company in The Netherlands.
We also changed the headers used in the welcome document, for example we changed Get organised, which is more a type of action, to the Dutch saying Opgeruimd staat netjes (Good riddance). Again, do make sure though to keep spaces, returns, placeholders, etc.
Coordinating the work
The key to a great localization is iteration and working together, polishing the translations until they feel right and consistent. Working together with the other translators helps a lot and divides the large amount of initial work as well. Above we already discussed some tactics including using the Needs Revision option_ as well as the language page in the community.
With regards to the latter, be aware that these are public pages so please keep things neat and be welcoming towards input from other users. They will be excited about the work you’ll be doing, but can also be opinionated, take their feedback along and be patient!
And, to make Agenda be even more successful in your mother tongue, it would be great if you could help us spread the word among your colleagues, contacts, peers, and local communities. Let us know if you need anything from our end if you think it would be of any help!
Working with us
Finally, when in doubt, hitting issues, or when having any questions? Don’t hesitate to get in touch! We’ll be around to help and contribute, to steer discussions where needed and to improve the app if needed as well.
Good luck and thank you so much for helping us bring Agenda to your favourite language, we can’t wait to see it!
Further reading: A great resource to learn more about the technical details of the localization process can be found here: Localization - Apple Developer
