User Tools

Site Tools


translator_guide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
translator_guide [2013/03/06 18:25]
lukakama
translator_guide [2014/10/17 11:06]
lukakama [Action activation phrases]
Line 1: Line 1:
-**This guide is intended for users that want to contribute on Voice Control translations.** 
  
-Currently, Voice Control translations can be edited and contributed using the [[http://​translate.voicecontrolapp.com/​|Translation Site]]. The site has registration disabled (to avoid spammer), but unregistered users can still suggest new or better translations that then will be approved and applied by a translation manager. 
- 
-If you want to request an account, just compile the [[http://​www.voicecontrolapp.com/​beta-and-translation-access-request/​|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 [[http://​weblate.org|Weblate]] project, and Voice Control 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 ====== 
-As a **quick guide**, on the [[http://​translate.voicecontrolapp.com/​|main page]] you can see the list of sub-projects and languages assigned to you as translator. Clicking on an element in this list, you will be able to open the translation details for that sub-project and language.\\ 
-From the translation detail page, you can then choose to open a set of texts to edit clicking on one of the available set displayed. For example, //All strings// allows you to translate every text for the opened sub-project,​ meanwhile //​Untranslated strings// will be shown only when there are texts not translated, and will allows you to navigate only between them. 
- 
-To edit your profile information,​ change email notification preferences,​ assigned languages etc, you can do them from the [[http://​translate.voicecontrolapp.com/​accounts/​profile/​|profile page]]. It can also be opened from the "​Logged in as" button on the top right of every page of the translation site. 
- 
-If you want, you can also read further information on how to use [[http://​weblate.org|Weblate]] reading his [[http://​weblate.readthedocs.org/​en/​latest/​usage.html|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: [[http://​developer.android.com/​guide/​topics/​resources/​string-resource.html|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 ===== 
-Voice Control actually is using various type of resources: "​[[#​Single value resources|single value]]",​ "​[[#​Plural values resources|plural values]]"​ "​[[#​Fixed multiple value resources|fixed multiple value]]"​ and "​[[#​Dynamic multiple value resources|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 [[http://​www.unicode.org/​cldr/​charts/​supplemental/​language_plural_rules.html|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 Voice Control: 
-^ 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 Voice Control)// | 
-^ 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,​ Voice Control 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 [[http://​developer.android.com/​reference/​java/​util/​Formatter.html|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: ​ 
-<​code>​ 
-Hi %1$s, today is the day %2$te of the month %2$tA of the year %2$tY. 
-</​code>​ 
- 
-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 ====== 
-Voice Control 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 Voice Control 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 Voice Control 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: 
-<​code>​ 
-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] 
- 
-</​code>​ 
- 
-Voice Control will load them as follow: 
-^ Phrase ​     ^ Tokens ​      ^ 
-|add event     | No tokens, Voice Control 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 | Voice Control will ask for missing and required variables | 
-|add event [EVENT_NAME] | EVENT_NAME variable available, Voice Control will ask the user only for the DATE variable | 
-|add an event [EVENT_NAME] | Voice Control will ask the user for the DATE variable| 
-|add the event [EVENT_NAME] | Voice Control will ask the user for the DATE variable| 
-|add event [EVENT_NAME] on [DATE] | All variable available, Voice Control will add an event with EVENT_NAME and DATE specified by the user | 
-|add an event [EVENT_NAME] on [DATE] | All variable available, Voice Control will add an event with EVENT_NAME and DATE specified by the user | 
-|add the event [EVENT_NAME] on [DATE] | All variable available, Voice Control 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 Voice Control 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 Voice Control 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 11:06 by lukakama