User Tools

Site Tools


translator_guide

This guide is intended for users that want to contribute on KLets translations.

Currently, KLets translations can be edited and contributed using the Translation Site. The site has registration disabled (to avoid spammer), but unregistered users can suggest new or better translations that then could be approved and applied by any registered user.

If you want to request an account, just compile the access request form. This way, you will be credited for your translations, and you will be able to configure notification preferences to be notified on other translation comments, suggestions, and so on.

The current translation site is based on Weblate project, and KLets texts are organized and separated into multiple sub-projects, in order to separate mandatory texts, that must be edited carefully and must be fully translated with each Play Store release, from low priority translation, that can be missing from a Play Store release.

Translation Site usage

Quick start

Inside the main page of the translation site there is the list of sub-projects and languages assigned to you as translator (they can be personalized from the profile page).

Clicking on an element inside this list, you can open its translation details page.

Inside the translation detail page, there is the list of available sets of texts to review or edit.

Set names are self-explainatory. For example, All strings allows you to open and navigate between every text for the current sub-project and language, meanwhile, Untranslated strings, that will be shown only when there are texts not translated, allows to navigate only between untranslated texts.

Clicking on a set name, you can open the first text available within that set, in order to start to review or edit translations.

From the text translation page, you can see the original English text, the editable translated text (empty if not translated), an optional comment (useful to better understand the original English text meaning) and zero or more suggestions provided by other translators or unregistered users.

From here you can:

  • Move to other set's texts: near the top, click on the first, previous, next or last icons to navigate between the set's texts.
  • Edit the translation: just enter or change the translated text and click on Save. Once done, the translation will be saved and you will be moved to the next text available within the set.
  • Accept or reject suggestions: just click on accept or reject icons of the suggestion. If approved, the suggestion will be applied to the translation and the page is refreshed (there is no need to save the translation to confirm the suggestion approval). If rejected, the suggestion will be removed and the page is refreshed.

Account management

To edit your profile information, change email notification preferences, assigned languages etc, you can do them from the profile page. It can also be opened from the “Logged in as” button on the top right of every page of the translation site.

Weblate documentation

If you want, you can also read further information on how to use Weblate reading his Documentation site. However, it is quite simple to use, so you can skip it.

Translation texts overview

Translation texts, also called Resources, must follows rules defined on the Android Developer Guide that can be read here: Android Developer Guide: String Resources. Most of resources escaping rules are automatically handled by the editor of the translation site, so you don't have to worry about them, but it is a good practice to keep them in mind.

Each resource is also associated with an identification key called context, that is used for organization and identification purposes, and can have some special meaning as you will notice below.

Resource types

KLets actually is using various type of resources: “single value”, “plural values” “fixed multiple value” and “dynamic multiple value”.

Single value resources

Single value resources are the simplest one, and they have only a specific value for each language.

Plural values resources

Plural values resources are used when the resource text form can change due a variable quantity (see Resources with variables), like you have 1 file and you have 10 files.

Considering that plural forms differs widely between the language families, Android handle them using Unicode CLDR plurals rules.

These rules define six categories of quantities named zero, one, two, few, many and other, where for each language are used only needed categories, and for which there are language specific rules for when they are used. For example, category one is commonly used when the quantity is 1, but for Russian it is used also for 21, 31 etc, but not for 11.

Below there is an extract of plural rules for languages used by KLets:

Language Category Examples Rules
Chinese other 0-999;
1.2…
other ? everything
Language Category Examples Rules
French one 0, 1, 1.2… one ? n within 0..2 and n is not 2;
other 2-999;
2.07…
other ? everything else
Language Category Examples Rules
German one 1 one ? n is 1;
other 0, 2-999;
1.2, 2.07…
other ? everything else
Language Category Examples Rules
Hungarian other 0-999;
1.2…
other ? everything
Language Category Examples Rules
Korean other 0-999;
1.2…
other ? everything
Language Category Examples Rules
Russian one 1, 21, 31, 41, 51, 61… one ? n mod 10 is 1 and n mod 100 is not 11;
few 2-4, 22-24, 32-34… few ? n mod 10 in 2..4 and n mod 100 not in 12..14;
many 0, 5-20, 25-30, 35-40… many ? n mod 10 is 0 or n mod 10 in 5..9 or n mod 100 in 11..14;
other 1.2, 2.07, 5.94… other ? everything else (actually Android doesn't support fractional values, so this category will not be used by KLets)
Language Category Examples Rules
Spanish one 1 one ? n is 1;
other 0, 2-999;
1.2, 2.07…
other ? everything else
Language Category Examples Rules
Swedish one 1 one ? n is 1;
other 0, 2-999;
1.2, 2.07…
other ? everything else

Fixed multiple value resources

Fixed multiple value resources can have multiple values and they MUST be in the same number and in the same order for every language (using as reference the English version). Currently the online-editor doesn't support them, but I'm working to improve it, so you will be able to edit them soon.

Dynamic multiple value resources

Dynamic multiple value resources can have an arbitrary amount of values for each language (from 0 to infinite) regardless the English version or other languages. Due Translation Site limitations, this type of resource are handled as a single value resource, where each value is separated by a “new line”. Additionally, KLets will strip off any empty line end every heading or trailing spaces for each value.

To know if a resource is a dynamic multiple value type or not, you need to check its context name (some resources are know to be dynamic multiple values, like command templates as shown below), or if it is highlighted inside the resource comments.

Resources with variables

Time to time resources need to have variable parts, like a date, a number, a name or everything else that can't be predicted when writing a resource value and that will be set at runtime.

Variables inside resources are handled using Android Formatter syntax: they are inserted with a “%” character, followed by the index in the form “n$” (like 1$, 2$, etc), followed by other characters that define how the variable must be formatted.

Example:

Hi %1$s, today is the day %2$te of the month %2$tA of the year %2$tY.

Variables could be placed in any order, and can repeated any number of time also with different formats (usually needed for dates), so they can accomodate any language specific needs about their placement.

For each resource with variables, there will be a comment explaining to which value each variable index will be set at runtime, in order to ease translation.

Resources organization

KLets resources are separated in 3 main sub-projects as follow.

Commands resource sub-project

This sub-project contains resources specific to voice input handling, like predefined command phrases for every action supported for a language, plus a set of other configurations specific for each language used for parsing (like dates parsing, contacts with number labels and so on).

Resources inside this sub-project are high priority resources: they need to be translated with care and must be translated for every language.

Action activation phrases

Action activation phrases are those that start with the context key action_, followed by a key that identify the specific action.

They are Dynamic multiple value resources, so, for each language, an action can have a different number of activation phrases.

Each phrase can contains variable parts that are marked using a special word in uppercase inside square brackets called “token”, like this [THIS_IS_A_TOKEN].
Tokens can be added or removed from phrases, but their contents must remain the same across all languages. Tokens, also, MUST be placed only one time inside a phrase and MUST be separated from other token AT LEAST by a single character word, otherwise KLets will ignore the phrase and will not use it to activate an action.

Action phrases, also, don't have to respect a specific case for text, because KLets will convert them in lowercase when loading them (except for the variable tokens, that must be written in uppercase).

Taking as an example the predefined English phrases for the “Add event” action (as in version 2.2.5), we have:

add event
add an event

add event [EVENT_NAME]
Add an event [EVENT_NAME]
add the Event [EVENT_NAME]

add event [EVENT_NAME] on [DATE]
add an event [EVENT_NAME] on [DATE]
add the event [EVENT_NAME] on [DATE]

KLets will load them as follow:

Phrase Tokens
add event No tokens, KLets will ask for missing and required variables when the action is activated using this phrase (EVENT_NAME and DATE for the “Add event” action)
add an event KLets will ask for missing and required variables
add event [EVENT_NAME] EVENT_NAME variable available, KLets will ask the user only for the DATE variable
add an event [EVENT_NAME] KLets will ask the user for the DATE variable
add the event [EVENT_NAME] KLets will ask the user for the DATE variable
add event [EVENT_NAME] on [DATE] All variable available, KLets will add an event with EVENT_NAME and DATE specified by the user
add an event [EVENT_NAME] on [DATE] All variable available, KLets will add an event with EVENT_NAME and DATE specified by the user
add the event [EVENT_NAME] on [DATE] All variable available, KLets will add an event with EVENT_NAME and DATE specified by the user

Main resource sub-project

This sub-project contains resources used for actions help and guide (displayed on opening screen), hint (displayed on recognition screen), template customization (displayed inside the action customization function) and voice outputs (text spoken with the Android TextToSpeech engine).

Resources inside this sub-project are high priority resources: they need to be translated with care and must be translated for every language.

Action resources

Action resources are those that start with the context key action_, followed by the action key plus additional text used to tell the final usage of the resources.

Currently, the following context key patterns are defined:

  • action_action_key_name: it is the user readable name of the action, and it is used inside the main screen (as action name heading above helps texts) and inside the action phrases customization function.
  • action_action_key_help: used to identify resources displayed as action help inside the main screen. Usually, this resources contains a brief explanation of the action and a couple of practical usage examples with predefined action phrases as defined in the Commands resource sub-project.
  • action_action_key_hint: used to identify resources displayed as quick hint while using the voice recognition, in order to quickly tell the user what actions he can say and how. if this resource is missing for an action, than KLets will auto-calculate it from default action phrases.
  • action_action_key_param_param_key: used to ask the user to tell the parameter.
  • action_action_key_param_param_key_help: quick help that explains what the parameter is expected to be. It is used for automatic hint text generation (for such actions without an hint resource), and inside the action phrases customization function when the variable selection dialog is shown to the user (when adding a variable to a phrase).
  • action_action_key_param_param_key_sample: quick practical sample of what can be said as value for the parameter

Other resource starting with action_action_key are additional texts used by the action (for example, to tell to the user that the command has been completed or that there are problems inside KLets settings, like missing accounts etc).

Miscellaneous resource sub-project

This sub-project contains resources used for options, error messages, alerts and other miscelaneous things.

Resources inside this sub-project are low priority resources: they could be missing for some languages, where english text are acceptable to be shown.

translator_guide.txt · Last modified: 2014/10/17 09:06 by lukakama