lupo manager online help

Welcome to lupo manager online help. Remember that lupo features a integrated help : use it by clicking the small question marks buttons eveywhere in the software user interface.

You can use this help for a better, more detailed overview of the software or if the integrated help did not answer your question.

If this online help was not useful, please post a question, bug report, or feature request, on lupo manager GetSatisfaction page.

Help Menu

Downloading, installing and registering lupo

Start page

Creating a new localization project

Source extraction

Bundle management

Code generation

FAQ

Known issues

Release Notes

 

Downloading, installing and license registration 

Once you've clicked on the PayPal Buy Now button and your payment is processed, you will automatically be redirected to a download page. This download page features an "install badge" you can click on to install this software. If the Adobe AIR runtime is not installed on your system, using this badge will automatically take care of that detail.

 Alternatively, you can use the direct link to download the AIR file. The AIR file is actually the installer for our software. If the Adobe AIR runtime is installed on your system, simply double click on the AIR file to begin the install process. If you don't have the Adobe AIR runtime installed on your system, you can download and install it from here.

 The download page also features your license key. Carefully note that down somewhere safe: it will be asked the first time you run lupo. Note that this license key was also sent to you by email, along with additional informations regarding your invoice.

If, for any reason, you did not note your license key on the download page and didn't receive our email, please contact us immediately so that we can send you back this license key and all other necessary informations.

When you first run lupo, you'll be asked to register using your license key. You will need to be connected to the Internet to perform your product registration. Remember that this license is attached to the system on which the software is installed. Once you've used it, you will be unable to install it on any additional system with the same license key.

However, you can choose to unregister the product license from the system at any time to install it on another system. To do so, use the "lupo manager > unregister" command in the main native menu. Once you've unregistered, lupo will close and ask for a new license key the next time it is launched.

Once you've registered, you'll be given access to the start page.

 

Start page


In the start page, you're given a choice between two options.
Choose "Open a existing project" if you have already created a lupo manager project, or you have been given one. You'll have to select an LPM file.

Choose "create a new project" if you want to start internationalizing a new application. Note that this application may already contain localization data. In that case, those properties files will automatically be imported.

 

Creating a New Localization Project


The single most important thing here is to set the project source folder. If you're using Adobe Flex Builder, this is your project "src" folder. Note that if your application uses many source folders, for example if you've added an additional source path to your project, you'll still be able to extract strings from those files. Just select the main source folder.

You can then select a locale folder, but most of the time you'll want to let the default option which will automatically create it. If your project already contains localized data, it will be imported. Your main locale folder (typically names "locale") does not have to be inside your project source directory (typically named "src"). If it's not, just select the right folder, and  make sure the folder structure is:
[mainlocalefolder]/[locale_code]/myBundle.properties
For example:

locale/en_US/main.properties.

The master language is the language which will be considered as the application's default language. It will be considered as the source language for translations, and will also be used as the fallback language in the software, (ie it will be used if no translation is found in the current locale).

The project name is only used to create the project's LPM file.

If your application does not contain any localization data yet, you can let lupo create a default resource bundle for you.

Once you've clicked "create", a LPM file (which is just a small XML file containing  the various data entered using this dialog) will be created inside your main locale folder.

 

Main interface

Lupo main interface in comprised of the project panel, on the left, and the main tabbed panel on the right.

The project panel is there to expose lupo's top level features, which can be used at any time of your development process. You can use it to add a new language, or to import and export localization projects.

You can also use lupo main native menu to access some of its features. Note that some panels, like the Preferences panel and the About dialog can only be reached through this main menu.

 

Adding a new language / locale

The top of the project panel lets you check the languages supported in your app, as well as the default language. Clicking on the Add a New Language button will open the New Language dialog. You just have to add the locale code here. Note that any string will do, but it is highly recommended to use ISO 639-1 language codes and ISO 3166-alpha-2 country codes, separated by an underscore, such as "en_US" for american english.

Clicking on the Add This Language will create a new folder inside your main locale folder, named after the provided locale code. It will also create one blank properties file for each existing bundle.

 

Exporting for translation / Importing translations

The Export button open the export dialog, which lets you create a new translation project. A translation project is a folder to be given to your translators. While you could create a single translation project for all translators, it is recommended to create one for each translator. This way, you'll select only the appropriate language(s), and the translator will have no chance to incidently translate the wrong language, nor will you import back the translations to the wrong files.

If your translator uses lupo translator, it will just have to open the resulting folder to select the LPT file, which will automatically open lupo translator.

Note that you can perfectly create a translation project with the master language as the target language.

The Import button lets you import translations back by selecting the LPT file. Of course, if you and your translator(s) share a network or a code repository, you can simply import the same LPT file lupo manager created during export.

After selecting the LPT file, you should see a dialog box saying which language(s) have been successfully imported. You can then check the translations in the Bundle translation panel. You'll have to save the current bundle (or your whole project), so that those translation actually overwrite the properties files in the main locale folder.

Source Extraction

When you open lupo manager, the Source Extraction tab is opened to let you parse the contents of your project's source directory. You can choose to parse another directory, or a single file, using the top left buttons.

The file combobox lets you see the currently select source file. Right next to this box, you'll find buttons to save the changes made to the selected source file, save and go to the next file, undo the last extraction, or undo all changes made to the file. Note that you can use the keyboard key "N" as a shortcut to jump to the next file.

The main text area lets you see the contents of the selected source file, and manually select a portion of your code to extract, like a string value. But most of the time, you'll use lupo manager search engine which will propose the strings that are the most likely to be localized.

About the search engine

The search engine uses regular expressions to find strings in MXML and AS3 files. In MXML files, only a subset of all strings found are eligible. In AS3 files, all strings are eligible. The regular expressions used by the search engine to look for strings, can be modified through the preferences panel.

For AS3 code, a smart engine can optionally apply additional rules to exclude some strings (whether it is in MXML or AS3 files), such as metadatas parameters, addEventListener() or setStyle() arguments, and many others.

Using the search engine control panel, you'll be able to navigate through the results. Note that you can disable smart search to let it select each and every string found in the selected file. This has no effect on MXML files.

You can use the keyboard arrow keys as short cuts for the search control panel: Right (next string) Left (previous string), Up (first string) and Down (last string).

Extraction panel

The extraction panel lets you define how to extract the current selection, and what to replace it with. You can select the destination bundle, the key name, and an optional comment to add before the entry in the properties file. Note that the preferences panel lets you automatically prefix the key name with the currently extracted file name (disabled by default).

A replacement pattern is shown by default, according to the current context: AS3 file, MXML code, or AS3 code in MXML file. You can replace it with your own. In this replacement pattern, '[BUNDLE]' will be replaced by the target bundle name, '[KEY]' by the key name, and '[TYPE]' by the selected value type (String, in most cases). Note that editing this pattern will also change the default replacement pattern for the selected context during this session.

Note that you can choose to modify the default replacement patterns via the preferences panel.

As the code added in your source file may require some classes to be imported, you can also automize import directive inclusion for both AS3 and MXML files.

Clicking the Extract button will perform the extraction, creating the key/value pair in the selected target bundle, and replace the selection in your source file by the code generated using the replacement pattern. Most of the time, though, you'll want to use the Extract & Find Next button to automatically jump to the next string after extraction. Use the keyboard "E" shortcut to trigger this Extract & Find Next action.

The Mark as TODO button does not do anything except adding a "TODO i18n" comment the line before the selected string. This way, you can easily remember to modify some parts of your code to better implement internationalization.Use the keyboard "T" shortcut to trigger this Mark as TODO action.

 

Resource Bundle Management


This tab is the place where your manager your bundles and their contents. The top part of the panel lets you select a bundle or create a new one, and save the changes made to all bundles.

The bundle master view represents the contents of the bundle properties file of the master language. For example, if your project's master language is "en_US", and the selected bundle is "Main" then the bundle master view represents the file
 [mainLocaleFolder]/en_US/Main.properties.

The master view lets you edit entries keys, values and comments, add new entries, remove entries. Note that when you remove an entry or edit a key name, this change will also be made in all supported languages. For example, if you have a key in your en_US
title=great application
... localized in fr_FR (french) as
title=super application
... renaming "title" as "myTitle", will also rename the french key, to keep translations in sync.

You can preview the resulting properties files, and save your changes.

Using the word wrap option, you can easily read all the text contained in the Value and Comments columns. Unselecting this option will truncate the text, but will still let you see actual (unescaped) line endings.

The bundle translation panel let you see the contents of the bundle properties files of all other languages. This panel is very similar to what your translators will see using lupo translator. You can see localized and original values side by side. You can also check the progression of the localization work.

Just like your translators (if they use lupo translator) you can use the option panel to use filters to only see non translated entries, for example. This is also the place where you can export and import translations as CSV files.

 

Code generation

The code generation tab is divided into three sub tabs:

The compiler tab generates:
- basic compiler arguments, typically used with Flex Builder' s additional compiler arguments text box.

-Framework resource Copies commands. These commands can be used to create copies of the Flex SDK en_US SWC and source files to a destination language. This is typically used when you encounter a " unable to open '[SDK]/frameworks/locale/[SOME_LOCALE]' " error.

-Resource modules creation command lines
Resource modules let you dynamically load and set localized data at runtime. Creating resource modules requires two steps : retrieving the list of bundle names used in this project, and compilling  the actual resource bundle. This section generates these command lines.


The AS3 / MXML tab generates:
-Bundle declaration metadata, which is required to compile localized data into your app. You can either paste this to an MXML or AS3 class file, or click on the insert button to automatically insert it in your project's main application MXML file. Note that this metadata declaration is required only once in your whole project.

The Quick test combobox is a very simple combobox which let users dynamically switch languages at runtime. Note that this is not intended for production, only for development.

The sample code is a slightly more complex AS3 code which helps you declare a human readable list of available languages, as well as a method to switch locales at runtime.

For serious projects, you'll probably want to have a much more robust way to implement i18n in your application. That's precisely what the Custom Generation tab is here for.
Calling resourceManager.getString(...) everywhere in your code has major drawbacks, including hardcoded strings for bundle keys (ie you won't get compile errors if you pass the wrong key name) and illegible text values in design views.
Using this tab, you can generate AS3 code via a pattern according to your bundle data.  You can imagine many scenarios from there. For instance, you may want to create your own class dedicated to localization logic, which would contain hard coded constants for each bundle key. You could also have a class implementing each key as a getter.
The two sample patterns correspond to each of those two scenarios, but again, the goal of this section is to let you adapt it to your very specific needs.
 

Common problems / FAQ

Q: When compiling, my IDE gives me the following error : Unable to resolve resource bundle "Main" for locale "en_US" - What's the problem?
A: To localize a Flex application, you need to add some compiler arguments : if you use Flex Builder, open project > properties > compiler. In the additional compiler argument text input, replace "locale en_US" by what lupo generated in the Code Generation tab > compiler page

Q:  When compiling, my IDE gives me the following error : unable to open '[SDK]/frameworks/locale/[SOME_LOCALE]' . Why?
A:  When you localize a Flex application, the flex compiler needs to find localized versions of all Flex SDK resource bundles for each language specified with the "locale" argument. You can use the "Framework resource copies" command lines found in the Code Generation panel to create copies of both SWC files and source (properties files) for your language. You'll then want to localize these.

Q: Can I use lupo to localize the flex SDK resource bundles?
A: Yes, you can. First create a new Flex library project using you favorite IDE. Create a new locale folder, and copy the Flex SDK bundle source files there. Then create a new lupo project and select the created flex project. Add the appropriate languages using lupo, and export a translation project, like with any lupo project.

Q: How do I use a proper font for the various languages my application supports?
A: Here's one way to deal with fonts. First, embed all necessary fonts in your CSS style declarations:
@font-face { src: url("EnglishFont.ttf"); fontFamily: myEnglishFont; }
Then, add a custom style for each of these fonts:
.someENFontStyle{ fontFamily: myEnglishFont; }
Add a new entry to your bundle's master language properties file:
MyTextStyle=someENFontStyle.
... and localize it
Finally, dynamically set the style name when necessary:
<mx:TextstyleName="{resourceManager.getString(‘MyRB', 'MyTextStyle')}"/>

 

 

Known issues

Extraction:
-The search engine can't find strings between simple quotes
-The search engine can't find mixed mxml attributes, such as label="{somevariable} text"
-The search engine doesn't ignore strings which could be ignored (eg constants)
-Syntax highlighting is disabled for large files
-You sometimes need to scroll the horizontal scrollbar to see the selected text
-Vertical auto scrolling often scrolls not much or not enough to place the selection at the center of the text area
-In MXML files, mark as todo breaks your code if the string contains a "<" character

Code Generation
-The quick test combobox generates a warning for using an Array in a databinding expression
-The metadata insertion in the application file is one big inline statement with no line ending (Note: this actually intended. It prevents a "only metadata is allowed" bug)

 

Release notes

Lupo Manager v 1.1

Bundle Master panel
-New feature: entries can now be ignored from translation by entering "@ignore" in the entry comment field
-Fixed a bug which could delete entries when a filter is applied
-Fixed a minor bug with search

Translation panel
- Fixed a bug regarding filters.
- Added a word count.
- Added a translation memory.
 

 

 

 

Adobe, the Adobe logo, Acrobat, ActionScript, Adobe AIR, Flash, Flex, Flex Builder, and Reader are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.