Intro
Ubiquity 0.5 introduces an updated command API, reflecting the changes in the parser as well as the new ability to localize commands. This tutorial will walk you through some of the key changes you will need to make. If you are interested in writing a new Ubiquity command from scratch, please refer to the updated Command Authoring Tutorial.
A note on (backwards) compatibility
Converting your command
names
Specifying semantic roles
Using semantic roles in preview and execute
Making your command localizable
Ubiquity doesn't yet support the localization of commands which are not bundled with Ubiquity itself. However, the localization of community commands is being planned, so making your command localizable now will future-proof your command and will later open your command up to a much wider target audience.
In addition to the Parser 2 API changes listed above, the main change to be made is to wrap any localizable strings in your preview and execute methods with the function _(). This _() command (familiar to anyone with prior experience with Gettext) handles the localization by finding the appropriate matching localized string on preview or execution.
displayMessage(_('No results were found.'));
In the case above, _() will then take care of finding appropriate localizations of the string "No results were found" for your command and, if available, display that string instead.
The _() function also handles renderTemplateing if you also give it an object with replacement variables. For examples, you can write the following:
displayMessage(_("${number} results found.", {number: numOfResults}))
By default, this will display, for example, "3 results found." if numOfResults == 3 and something like "Il y a 3 résultats" given a French localization of "Il y a ${number} résultats". This templating can also be used to handle pluralization—please refer to Making Commands Localizable for more information.
There is no need to wrap any properties of the commands (names, help, author, etc.) in _(), nor do you need to wrap string previews in _(), in order for the command to be localizable. These direct properties of the command are automatically localizable as long as they are set in the original command.
More tips on making strings localizable can be found in Making Commands Localizable.
References
- The updated Command Authoring Tutorial
- Semantic roles in Parser 2: a list of supported semantic roles with explanations and examples
- Making your command localizable