/ Development  

Using translations in your solution

Hi there AppWorks fans,

Welcome to a new installment of AppWorks tips.

For this week, we put the basic translation options of an entity modeling solution to the test. Why? Well, I see a lot of questions and problems showing a crafted solution into the native language to the end-users. What I also see in the field is building solutions directly in the native language! Please stop this mindset; I always recommend to build a solution in the English language en-US and translate afterwards. This post will show you the mindset of working with translations the correct way on the AppWorks platform…

Let get right into it…

…and jump straight into a basic crafted ‘Project Management’ application looking like this with some basic screenshots:

Project creation

translations_001

Project view layout

translations_002

Homepage overview

translations_003

Notes:

  • My environment is clean from any crap and garbage
  • There is no language pack applied (yet!)
  • I run it all with a ‘Developer’ role account called ‘awdev’; I know…Not a best practice, but sufficient for the post.

From a design-time perspective, this application is built only with the English language in mind (technical values and the labels too); Just trust me on that one! 😇

Alright…We have an English solution! Time for those translation skills…

Enable language pack

OpenText is not sitting still and the basic runtime UI for the end-users is already translated for you. My native language is Dutch (nl-NL) and for this section of the post I follow my own language pack post. In quick steps:

  • Deploy the ‘Cordys BOP Language Pack_nl-NL’ from the /app/system shared space using the ‘Application Deployer’ artifact. I use the ‘sysadmin’ account to accomplish this task.
  • Restart TomEE with systemctl restart tomee
  • Open the runtime UI and apply parameter ?language=nl-NL to the URL like this: http://192.168.56.107:8080/home/appworks_tips/app/start/web/?language=nl-NL

These are my views with the language parameter…The ‘red’ sections are my own not-yet translated features (the rest is nicely translated in nl-NL)

Project creation

translations_004

Project view layout

translations_005

Homepage overview

translations_006

For the full clarification, the language used to fill values in the fields during entity creation is up to your end-users! We as developers and administrators are not in control for this input.

Let’s solve those ‘red’ flags in the next section.

Apply a language local to the project

Go back to the ‘Workspace Documents’ artifact and right-click the project. Go to submenu item ‘Translation’ and open the ‘Translate’ option. From this panel you need to open the ‘Language Settings’:

translations_007

Don’t make the mistake to first add the language from the context menu…It’s not working correctly from what I experience!?

In this new panel, you need to add a new language; In my case nl-NL:

translations_008

Don’t be smart to use language code nl as I have some mixed feelings about it. I know the parameter ?language=nl also works, but it smells different from the ‘nl-NL’ version which is more solid in my opinion…Comment me otherwise!

In the screenshot above, you also see the ‘Project Language’ setting. Don’t touch it and just leave it English as this will be your main language in design-time. Remember my statement: Develop in English; translate runtime afterwards!

Hit OK for the language settings panel, and you get back to the ‘Translation Editor’ with our Dutch language as new column:

translations_009

Time for some translations…I don’t hire anyone, but just do it on my own! 💪 As far as I get it, you only need to translate the missing parts as this project specific translation lands on top of the installed ‘nl-NL’ package. So, in the list of translations you will see platform specific identifiers passing by (e.g. ‘Discussions’), but just skip those to keep them in place from the language pack itself!

Ok, when all the translation are in place you can do a publication on it. I also recommend to do a clean output on the project and publish the project again to see a direct result in runtime like this:

Project creation

translations_010

Project view layout

translations_011

Homepage overview

translations_012

Final notes on the three translated screenshots

  • ‘My Inbox’ is not translated, but we’re not in control as it’s part of the identity package of the platform. Support!?
  • ‘Draft’ for the lifecycle status in the list is not translated for some reason; This is strange as the lifecycle progress panel is showing the correct translation. Looks to me like a platform translation bug; On the other hand we should be able to make a nice workaround with the help of an ‘Integer’ property, an event ‘Rule’ BB, and showing a progression bar in the list instead! Just a thought…
  • ‘Default template’ in the ‘Contents’ BB panel was not on the list of translation identifiers. Looks also like a platform translation bug, but we can overcome this one.

Well, that’s it!? Wait!…There is more behind the wavy green landscape of entity modeling…

More on translations

  • The low-code guide has a section “Translating entities” where I read it’s possible to switch the language for the entity display name and the property labels from design-time; Nice feature but trust me; In the long-run you want to develop in English and translate afterwards. Although the list of translatable identifiers can get long. I also tried it out, but it isn’t working as described…Maybe I’m doing something wrong, but I leave the choice to you; I keep it with my own recommendation.
  • The advanced development guide is also full of translation features:
    • xForms UI: An xForm (aka. ‘User Interface’ type of document) is not my first choice to implement a feature. If you do it, you can right-click it for the translation options.
    • ‘Translation Manager’ artifact: This one is found in the documentation, but I couldn’t find it as separate artifact in design-time? I guess they just mean the translation options from the project context menu.
    • BPMs and ‘Business Identifiers’: Works the same as an xForm; Right-click on the BPM or BI (?) document for the translation options
    • HTML5SDK with JS message bundles: I already make a post about the HTML5SDK; To add translation support you require to create new documents of type ‘JavaScript Message Bundle’ which have that same translation option in the context menu of the document. I recommend to read the guide on further implementation and the usage in your custom HTML page!
    • Localization bundles: You use these when you want to translate system activities, errors, or warnings. I recommend to also grab the guide for this one. It’s a step-by-step process where you synchronize your workspace to the server, create location XML bundles and pull them into your workspace again via a synchronization. You can use these localization XMLs also in custom code like for example the EIS connector or a custom documentstore connector, but this is out of scope for this post.
    • Localizing WS-AppServer messages: This is also a specific section in the development guide but works with the same localization XML bundles from above. Read the post ff you don’t have a clue about the WS-AppServer.

…

A “quicky” on the option reconstructing missing translations…The ‘missing’ part can happen in these situations?

  • Moving documents to other projects
  • Validate/publish projects
  • Synchronize projects with file system to/from the server
  • Making changes available for others (SVN) and retrieving from others

In these cases you will start to see those strange translation files with a unique identifier (e.g. 0050569e-1d18-a1eb-adc4-4cd8efc73e71) popping up in your project; especially with multiple developers!. These are the same kind of files you see when you have a closer look at your project sources after a synchronization or when you get a closer look at an extracted CAP file!

translations_013

…

To finalize the post, we end with an option to translate the OTDS login page. Why? Because it’s recommended by OpenText to use OTDS as an identity provider. The login page will follow the default browser language. If not, have a look into the OTDS administration guide to find yourself the option to add a new system attribute: directory.auth.ShowLangsOption=true. This will show a language-switch icon on the login page (at the bottom). To restrict the list of languages behind this? Have a look How do I remove the availability of a certain language in OTDS? in the manual of OTDS!

A nice “DONE” where we learned about the importance of developing a solution in the English (en-US) language and translate the labels to the native language in runtime for your end-users afterwards. This way of crafting a solution makes your solution feature ready on new native languages. It also separates translations from the solution which makes it possible to let others do the translations for you. Great stuff…Have the best of all translation weekend, and I see you in the next post on AppWorks Tips; next week!

Don’t forget to subscribe to get updates on the activities happening on this site. Have you noticed the quiz where you find out if you are also “The AppWorks guy”?