Localization Guidelines and Tips

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 OneSky web application, as well created an account that allows you to log in.

Overview of the OneSky interface

Translating Agenda is done through the OneSky web platform. When you enter your account details the main window will load the list of 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 yellow 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 next 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:

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 OneSky 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 OneSky 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 ⌘-D 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 ⌘-S 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.

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 translate.google.com:

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 as often it suggests terminology from the Android platform, which can be subtly different sometimes.

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 %@?”
  • %d which 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.

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:

Screenshot 2020-05-15 at 19.23.48

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)
    • 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 OneSky 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:

08 13

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 in OneSky_ 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: https://developer.apple.com/internationalization/

1 Like

Handling new and updated translations

Agenda continue to evolve. Bugs are fixed, new features are added to Agenda, and feedback and suggestions are listened to. This means that translations need to be added and kept up-to-date. Below you’ll find some examples of how to deal with the ongoing changes.

New phrases

As new features are added, new phrases are added to Agenda. These will show up as Untranslated in the overview, selecting them will filter them out for you:

For these you’ll have to enter the translation, following the Guidelines above.

Tip: If the English sentence contains placeholders like %d or @count@ you can start by copying in the source text using the ⌘-D keyboard shortcut. This prevents any mistakes in adding the correct placeholders.

For a complete list of keyboard shortcuts, check the button in the lower left corner:

Previously translated

Sometimes the new phrases already appear in other parts of the app and therefore have already been translated previously. In that case your life is made a bit easier and all you need to do is select the matching translation from the Suggested phrases on the right:

Changes in the English (source) phrases

Another common scenario is when existing translations are updated, tweaked or corrected. This results in phrases where the English source text was changed, they can be viewed by selecting the following filter:

You will encounter two scenarios:

Changes that don’t require a change in the translation

For example, this change from UK to US english doesn’t require the Dutch word for holidays/vacation to change:

All that you have to do is to approve the existing translation using the blue checkmark if there is no need to change the translation.

Tip: To see more easily what changed exactly in longer phrases you can click the red exclamation mark to get this dialog that allows switching between the old and new translation:

Changes that do require a change in translation

If the English phrases changed meaning or had additional details added, etc, you should update the translation, for example here html was changed to HTML, which needs changing in the Dutch translation as well:

After you have edited the translation, submit it by checking the blue button.

Final checks

Before finishing the updates, be sure to check that the two more filters Not translated and Not approved have no remaining untranslated phrases:

For technical reasons it can happen for example that some phrases might not appear under Not Translated but have an English translation still, these usually appear under Not Approved. Be sure to check these as well.

Wrap up

And once you have completed everything, be sure to let us know by leaving a message in the shared discussion with your language group, we can then update things for the next round of releases! :tada: