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 download link to the Local Agenda application, as well a translator key that allows you to log in.

Overview of Local Agenda

Translating Agenda is done through the Local Agenda app we build for this purpose. When you enter your translator key the main window will load with a typical master-detail view:

Tip: While Local Agenda is available as a mac, iPad, and iPhone app, we strongly advise to use the mac app for the majority of especially the initial work (you probably will want to have Google translate open in your browser for example).

On the left you will see a sourcelist will individual translatable items. At the top you’ll find both a search field as well as a filter button that allows you to filter on those items that still need work only:

15

The items in the sourcelist are also color coded by their state (see below), which also helps to focus on those that need your attention.

Clicking on an item in the sourcelist shows the details for the item on the right, starting with the original English phrase/word, and optionally (but importantly!) a comment or description explaining in more detail where/how the word is used:

29

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 the English original phrase/word, you’ll find the area where you should enter the translation in your language:

It also comes along with a set of buttons through which you can indicate the current state of the translation:

  • Blue - Untranslated: nothing has been filled in yet
  • Purple - Translated: a translation has been provided but it hasn’t been verified yet
  • Green - Verified: the translation has been reviewed and approved
  • Red - Disputed: one of the reviewers or translators has marked the translation as needing review

Below these buttons is shown who has made and verified the translation, respectively.

Finally, there’s an area where translators and reviewers can leave comments, for instance to ask question, make suggestions, explain rationale etc:

09

Note: There are a few known issues with the Local Agenda app that you might hit while using it, be sure to check out the Localization Guidelines and Tips post below.

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. The list itself can be divided in two parts:

Prefilled translations

Throughout the list you’ll find a set of phrases and words that already have a translation and are thus marked as purple. These have been translated using Apple’s Glossaries (see also below) where we have identified exact matches with translations provided by Apple while we were translating Agenda to Dutch. These will help you settle on a number of nouns and verbs that are also used in other apps, as well as standard main menu items for example. Note that this doesn’t mean that they are all correct, you will still need to verify them and you can also change or tweak them if needed (for instance by changing capitalisation etc). If you approve a pre-filled translation you can mark it as verified, which should change it to green.

The second and largest part of the list will need a translation from scratch, marked as blue. Once you have filled in a translation you can mark it as translated, turning it from blue to purple.

This means that after round one all entries would have a translation, with about one third in the green verified state (the prefilled translations) and the rest in the purple translated state (which the other translators will verify in the second round).

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 pre-filled 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.

Glossary

To help you find the correct translations, we’ve added the Apple glossaries for you to inspect. You can open these by clicking/tapping Show Glossary button at the top right corner of the box where you fill in the translation:

What this window shows are Apple provided sentences and words that contain the words in the original english counterpart. It allows you to check what kind of verbs and nouns Apple has used for similar phrases and words.

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

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?”

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:

28

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).

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 Local Agenda. Is everything translated and marked as verified? 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 in Local Agenda, along with marking the translation as disputed 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 Disputed option in Local Agenda 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

Troubleshooting Local Agenda

The Local Agenda app is a so-called cross-platform Catalyst app, written using the new SwiftUI frameworks Apple introduced at WWDC2019. In large we decided to use these technologies so we could judge it’s potential use in further developing Agenda and how it would stack up against the technologies we have used so far. While the app works ok, it unfortunately also shows that it’s still early days for these technologies. There are some rough edges and below you’ll find the most common issues we’ve encountered. Let us know if you hit any others.

Minimum system requirements

Local Agenda requires a mac running 10.15 or higher, or an iPad or iPhone running iOS/iPadOS 13 or higher.

Editing text is slow

Alas, this is one of the issues we hit that made us conclude the technology isn’t ready yet. We will try to make it faster but for the moment it is what it is unfortunately.

The sourcelist no longer allows to scroll

Unfortunately this is a bug in the current implementation of SwiftUI/Catalyst, the only solution is to force quit Local Agenda and start it again. Note that a regular quit and restart of the app does not work as Catalyst apps stay running even if you quit the app.

When I select a translation in the sourcelist it rescrolls to a different location

Unfortunately this too is a bug in the current implementation of SwiftUI/Catalyst, there’s no fix at the moment of writing other than to scroll back to the selected item.

If you have other issues or want to leave feedback, see this topic:
Feedback on Local Agenda App