Building a Multilingual App

Introduction

Multilingual - what do we mean by that?  Well, “multi” means more than one, and “lingual” has its origins in the Latin word “lingua”, meaning language… err in other worlds we’re talking about a single solution that can speak more than one language :)

Why would you want many languages?

In most cases, a solution is developed using the most common language of the user of that solution. But what if the solution has many users across many geographic regions and who speak many different primary languages?  

Being able to present a solution to a user in their native language is a real benefit and widens the market for a solution that you may sell as a product, or indeed any solution you develop to be used in many countries. Even within a single country many languages can be spoken so being able to give users the freedom to select their language of choice is going to greatly improve their user experience.

Is this for everyone?

In short, no. Building a multi-lingual solution takes time and planning. Once the key framework is in place for adding multiple languages it can be quite efficient to develop with but it will always be a slower to build than if you just ripped into development using a single language.

You need to think carefully about whether the solution you intend to build will ever potentially be used by individuals who may have a different native language to the one the solution is developed in, and whether you want to make that investment up front. It is much harder to make an existing solution into a multi-lingual one than it is to begin a solution from scratch to be multi-lingual.

Before we get into things, grab the example file!

For the remainder of this article we are going to use the associated example file as our reference.  I strongly recommend you download the example file and have a look (and read) through it as you read this article. The example file includes many different scenarios that you will encounter in building a multi-lingual solution and also contains a lot of helpful information about each.

MultiLingual.zip

The first table is Languages

It’s pretty straightforward really. Each record in the language table is, yup you guessed it, a language. 

As you can see above we have established three languages in our example. The information we capture is again very simple: name, abbreviation, icon and a flag field indicating whether this is the primary language in the solution. It is really up to you the developer as to how you decide which language a user is to use.  Almost certainly this would involve having a User table, where each user stores their individual preference for what language they want to display the solution in upon opening the solution. If it is a brand new user however, or if the user has made no preference, then the default language can be used and set on startup.

The next table is Phrases

Think of a phrase as having no associated language, it is merely some form of written text within your solution, that you are going to be required to translate into a language. For example, a particular phrase may be a label for a name field, it may be a label on a button, a tab control, or it may be an item in a value list.

Phrases can also be for specific records. You may for example have a table in which you have records for your solutions navigation - each record being a link to a screen in your solution. These are going to need to be translated, so phrase records can be setup and linked directly to each record. We’ll cover more on these later, but for now think of a phrase as purely something to be translated.

Here in the table above we have the phrases setup in the example file. By looking at this you may start to have some light bulbs going off as to how we are going to achieve multilingual functionality through global variables.

In our phrase table we have essentially 3 different category fields named type, category and sub category. The description is purely for our own purposes to help the developer identify what the phrase is actually pertaining to.

The variable name that you see is a calculation and we build the name based upon the users nominated type, category and sub category.

We should point out here that this method of categorising your phrases is just one such way in which you can do this. This part of the process is entirely up to you the developer as to how you want to identify phrases, and thus how your variables are going to be named. You may simply want 2 categories, you may want none, or you may end up with more, it’s up to you.

Variable Names are really important!

So if you haven’t clicked by now, each phrase has an associated global variable name. The way in which we will do multiple languages, is to store into these global variables the translation of the phrase in that of the users chosen language.

This method requires that variable names be used throughout your solution, from calculations on button bars and tab controls, to merge fields on your layout, to within calculations and scripts - there is an element of hard coding throughout your solution of variable names.

We do this primarily for readability.  Looking in the data viewer will give you the full list of all of the language based variables used so you can easily reference them. It also makes it easy when looking at layouts and calculations to ensuring you are using a correct global variable for a given purpose. At the end of the day, hard coding is going to be done, so we may as well make these as readable as possible.

But the drawback to this is that you must make sure you name your variables in such a way that you are happy with them, and that you are not going to go back and change the naming down the track. If you end up recategorising your phrases, it will mean you have to change variables names accordingly in your solution, which can be difficult if you don’t know where they are used. Applications like BaseElements and FMPerception can help with this.

If you wanted to make a modification to the framework, there is no reason why you couldn’t simply name your global variables by using a Unique record identifier (UUID) of the phrase record instead. The benefit is variable names won’t change as the UUID won’t change, but the drawback is your global variables become unintelligible and you cannot simply look at them to know what they are. That is why we go with human readable names.

The key takeaway here is to get your categorisation and naming convention correct early so that you're happy with it... and that you won’t change it!

And Finally, Translations

The final table we are going to require is called Translations.  The translation table is simply a join table between Languages and Phrases. Each Phrase is going to have 1 Translation record per language.  The translation record will store the actual translation of the phrase into the nominated language, and that’s pretty much it.

In our example file, we define are translations using a specially constructed portal as shown above. The portal is filtered based upon the user choosing a nominated language from a drop down above. What the portal shows is actually phrase records, but inside it we place a translation field. We have constructed a special relationship with “allow creation of records in this table via this relationship” enabled. This makes it really easy for us to define the translations for every phrase for a chosen language.  We simply change the drop-down to the next language and then we can create our translation records for that language.

Above we display the type of phrase record, its descriptions and categories, and its variable name so that we clearly know what it is we are translating. 

Putting it all together - the basics of the framework

So that’s about it really for the table structure of our framework, it simply consists of 3 tables - Languages, Phrases, and Translations.

The next stage of the framework is defining all of our phrase global variables for a given language, so lets look at how we achieve this.

How variables are defined

We saw earlier that global variable names are defined on the phrase table.  It’s a calculation, and we are using our category names to define our variable name. We also strip out any spaces or illegal characters from the variable name, replacing with underscores.

When your solution is opened, as part of the startup procedure, we will be required to define all of our global variables and give them a value for a given language. So we should at the very least know the language we want to use - this will either be the system default language, or a language based on user preference.

In our example file we have 3 key scripts responsible for management of languages.  The first “Load Language” is really the only script you require. You pass it the primary key ID of a language to load, and it does so.  The other two scripts are helper sub-scripts.

The basic process of Load Language is:

• Obtain a list of all of the variable declarations for given language
• Evaluate these declarations, thus loading them as actual global variables.

And that’s all, pretty simple really.

Variable Declarations

So, we know the language we want, and so using this knowledge we can find all translation records for that language.  On each translation record we have 2 special calculation fields, named variable_set and variable_clear. 

What these calculation fields are defining is a string which represents either setting the global variable to the value of the translation record, or simply setting the global variable to empty.

As an example, here is the variable_set calculation:

PHRASES::variable & " = " & Quote ( value ) & " ;"

We grab the associated variable name from the phrase, stick in an “=“ sign, and then he translated value in quotes, followed by a semicolon.  This is exactly how we would write it if we were defining this global variable in a LET Statement, and in fact that is exactly what we are going to do. We are going to build up a Let statement containing all of our global variables declared to their translated values, and then run that statement using the “Evaluate” function.

This is what the 2 helper scripts achieve, they help retrieve all of the required variable declarations, and then build the LET statement before finally executing it.

How it actually achieves that is something we’ll leave up to you all to explore in the example file. The scripts are designed to help load all the variables successfully. One limitation is that of the size of a calculations definition. To overcome this for large solutions which may have thousands of translations, we chunk declarations into no more than 500 at a time, so that we never hit the limit of a calculations definition.

To cut a long story short, this is what we get…

After calling our Load language script, what we end up with is something like this:

This is our data viewers current tab, and inside it you can see all of our global variables loaded up with words.  Note that we use the LANG prefix on all global variables that are to do with the language of the solution, this just helps us keep them all grouped together. 

We also store the ID of the selected language in a special global $$LANGUAGE.SELECTED_ID . This has benefits later on which help us overcome some other challenges with multi-lingual implementation, so it is important to know at all times what the current language is.

There are also some special META variables defined. This is loading in information about the current language which we may wish to display on-screen to the user. They’re loaded in as variables in case they ever need to be used, but they are not critical.

What are these?

You may note that at the bottom of the list of global variables are some odd looking variable names:

They certainly are not the categories we have defined for our phrases, so what are they?

These are special translations that are not for text that may appear on a layout directly (such as a label, tab or button).  They are translations for words that exist in records within the solution.  In fact this is one of the challenges of a multi-lingual solution that must be overcome - there are often times that data residing on records within a solution need to be translated.

What type of record data are we talking about?

It is very important here to make a distinction about what kind of record data we’re talking about translating. We are NOT talking about user-entered record data. We have no control over what data a user will type into a text field for example, and so we simply cannot provide translations for every possible thing they may type, that is ludicrous!

 What we are talking about here is record data that we know exactly what it is, and that will not change.  Typically this is record data for use in value lists for example, or record data for user interface purposes, such as a navigation portal.  Both of these examples are covered in the example file using this method, and we’ll talk about these a bit more later.

Defining a “Record” type Phrase.

Previously we were just talking about phrases for standard text in your solution on layouts, buttons and so forth. They were defined using categories.  Record phrases however are defined using the Primary Key ID of the record that is being translated, along with a special keyword to identify what it is on that record we are translating. Our phrase table has a type field named “phrase_type” that is set to either “Variable” or “Record” which helps us define what type of phrase it is. 

For record based phrases, we still use the category fields, but instead, our primary category is the ID of the record being translated, and the sub category is keyword to help identify what on that record is being translated. The keyword is important because there may be times where a record has more than one field that requires translation ,so the keyword helps create different variable names for each field being translated on that record.

Okay, time for a quick recap!

We’re about halfway through now, so lets just quickly recap what we have covered:

• 3 tables - Languages, Phrases, and Translation
• For a given language, we generate global variables, 1 per phrase, that contain the translated word for chosen language
• We can then use these global variables throughout solution where required, e.g. labels, buttons, tabs, calculations, scripts etc.
• We have special global variables that are tied to a record/field to be translated (more on this shortly).

 So it all boils down to a pretty simple framework really.

Let’s see it in action

Here’s an example of a layout that uses the global variables:

You can see some merge-variables used for the field labels. The buttons (which are button bar segments) have calculated values set to global variables. The tab names are calculated global variables. And even the merge field contact_display_title makes use of a global variable.

This is a great example actually of how we achieve multi-language in calculations. Lets look at that calculation in more detail:

We have a contact chosen. We start by getting their name.  We also grab the translation of a special phrase used if no contact name is provided.  Next, we take another phrase we use for the string, and we replace a piece of defined placeholder text <<NAME>> with a value, that is either the contacts name, or our special “no name” phrase.

If we look at the phrase definitions used:

You can see in the first phrase we have our <<NAME>> placeholder. This is how we can insert actual record data into a translated piece of text.

The second translation is what we will display if a contact has not been given a name.  Here is what it looks like in browse mode:

Pretty cool huh?!

Keeping data-entry as simple and universal as possible

Now we are going to get into some of the more challenging aspects of multi-lingual solutions, the first of which is value lists.

But before we get stuck in we need to be clear in our understanding of what is translatable in a solution, and what is not.  Earlier we stated that no user-entered record data will be translated and we stand by that. You simply cannot provide a translation for what a user will type in as data on a record. For example, if you have an english-speaking user enter contact names, then those contact names are almost certainly going to be in english. If you have a Chinese person enter contact names, then they’re going to enter them in Chinese. Differences in the languages of entered data is something you just have to live with in a solution.

There are some situations however, with careful planning that you can avoid these conflicts by being smart about the format of data that users are entering. So what do we mean by this?

Lets say you have a field in your database called “Test Complete”. This is a straightforward boolean field with either a yes or no response. The user chooses a value using a value list.

One way of data entry would be to provide the user with a value list of “Yes” and “No”. These are english words, and if you do that then the user is actually entering english words in as data onto that record. Then, what if a Chinese person then wants to enter data? Will they know the meaning of Yes and No in the value list? 

The solution to this problem is to at all possible opportunities come up with a universally recognised method of data entry that has the same underlying meaning across all languages.

In this case, don’t use words. Instead, use a check-box. Store a “1” as a yes response, and store an empty value as a “No” response. Present it as a check-box to the user. Everyone understands the concept of a ticked box meaning “Yes” versus an unticked meaning “No” regardless of their language of choice.

By providing the user with a visual means of data entry, like a check-box, versus a textual means of data entry like words, it means the method of entry becomes universally accepted and understood, and you remove any confusion you would otherwise have by presenting words to the user. The users need never see the actual underling fields value, providing it is always visually presented in a universally accepted format.

For times when this is not possible, a value list is required

Check-boxes are the main example for where you can universalise data entry. Another would be using colours for things like a priority value. But generally you will have to display a value list to the user for the purposes of selecting a value.  So how do we present a value list in a users native language?

One problem we have in FileMaker is that if a value is chosen in one language, then the value will not appear in a value list based on a different language.  

The solution is to think about storing where possible the primary key record ID’s, instead of the actual textual value.

Here is a great example of this - selecting a country.  A country will always be the same country regardless of its name - the name is just a means to identify it. So if you need to select a country on a record, why not just create a table of countries, and store the ID of that country record?  This is another way in which you can universalise the data entered. A primary Key is a primary key in any language, and in most solutions we develop users will never be exposed to a primary key value anyway, to them it is meaningless.

If value lists become tools for selecting primary key IDs, then what the user actually see is purely a visual component, and something we can manipulate to display in the users chosen language, and that is exactly what we do!

Again, it is important to note, we’re talking here about record data that is known, and not likely to change or be modified by a user. We can easily build a table of countries and base a value list off that.  If instead we were to build a value list of contacts names and IDs, then we cannot translate contact names, and so a user in any language will always see just the names as they were entered onto contact records.

In our example file, we have a table of countries on the left. Each country has an ID, and a name. The name in this case is purely to help identify the record, and is likely to be in the developers native language. We won’t actually be using the country name on this record for display in a value list, instead we’ll be displaying a translation of that name instead.

The table on the right is phrases, and we have 1 phrase record per country record. We link the phrase record to the country record through the countries primary key.  We are using a keyword “country” as the phrase identifier.

We define translations for the phrases in the exact same way we did previously:

But in this case you’ll note we are dealing with phrases that are of type “record”.  The variable name contains the countries primary key value, and a keyword “country”.

Defining the Value List

This is not trivial unfortunately, and it’s a bit of extra leg-word to get the value list properly setup, but once done, it is really cool, promise!

Think about what the value list actually needs to contain:

• The ID’s of Country records
• Displaying the translated value, from the translation records. 

The country ID resides on Phrase records, and the names reside on translation records. So in our definition of the value list, we need to relate to all phrase records that are for countries, and then relate to the translations for the selected language.

Here is the first relationship, from our base table occurrence (which could be anything really), to phrases.  We have 2 predicates. The first is finding all phrase records for a specific set of primary key values (country IDs), and the second is linking to the specific keyword which is “Country”.

In fact, this is a bit overkill. If we wanted, we could actually just relate on the keyword “country” providing it is unique.   However the reason we do it as above is by relating to a specific set of records matching on ID’s, we don’t necessarily have to have a value list based on every phrase record for countries. We could control which countries are in our value list based on which ID’s we have on the left hand side of the relationship.

In this case however the field “country_ids” on the left is basically a return-delimited list of every country primary key ID.

Okay, so we have now a relationship to all phrase records for countries.  This serves as the basis of the first field in our value list. We will be using “category_primary” as the first field. Recall this field actually contains the country ID.

Next, we have a relationship to translations.  We first match on phrase so that we are only getting translations for the given phrase record. We then must filter further to the specific translation record for the language the user is currently viewing the solution in.

Recall earlier we defined a global variable $$LANGUAGE_SELECTED_ID. We are now going to use that in the calculation field _CURRENT_LANGUAGE. This calculation simply contains a reference to the global variable.  Each time the language is changed by the user, the value of this calculation changes, and thus the relationship to specific translations changes to just those for the user chosen language.

Here is our value list definition:

As you can see, the first value is the country ID, second value is the associated translated country name for the users chosen language. 

We only show the displayed value, the user has no reason to see the ID or care that they are actually selecting an ID.

Putting it all together here is what it looks like, first in English:

and then in German:

Note that regardless of the language chosen, the actual country chosen remains ticked in the value list and is displayed to the user in their chosen language.

Phew! We made it!

Value lists are tricky, and are indeed what we believe to be the most tricky part of a multi lingual solution. But they are possible and once you get the hang of how it works actually quite easily to setup and use.

The next example is very similar to value lists as it involves displaying record data however this time it is not data the user is going to be entering into a field, it’s purely a visual/user interface thing. 

Translating data in records for layout display

Often we’ll want to translate record data to the user where the record data is used as part of the interface. A classic example is building a portal-based navigation system, where the labels of screens will exist as data in a table.

Here is a simple portal containing records from a Navigation table. Each record corresponds to a layout in the solution the user can go to, or a function the user can do, such as logout.

Here is our table setup and phrase setup. This is identical to that of the value list setup. We have a navigation table on the left. The screen name here is purely for the developer to help identify what record is what.

The phrase table on the right has 1 phrase record per navigation record, with an identifier “navigation”, and description. 

Now, you may wonder why even bother with a navigation table, why not just put your navigation directly into the phrase table? Well there is no reason as to why you couldn’t do this. You could simply treat the “Navigation” records in the phrase table as your actual navigation records. The reason why we don’t do this is we wan’t to keep the language, phrase and translation tables purely for multi-lingual purposes. We don’t want to clutter them with user interface elements or value list data. This is why in both the value list and this example we still have a separate table containing value list data and record display data.

Anyways, back to the example!

Once again, the exact same setup of translations as before, we just choose a language and define the translation. Note the variable names here again contain the navigation ID and keyword.

Making use of having the ID in the variable name

We now finally can make use of having the record ID’s contained within the variable name. In the value list example while we still had variables declared for countries, we didn’t actually use them for the purposes of the value list. However in this instance we are going to make use of them. 

Given a navigation record, we know what its ID is.  We also know that it is for navigation. These 2 pieces of information should allow us to calculate what the global variable name associated with the record is. We know all language variables begin with $$LANG. We also know that the ID follows this in the variable name, and we know the Navigation keyword is on the end.

To help us obtain the correct global variable, we have built a custom function, named @LANGUAGE_GetRecordTranslation

This function receives 2 parameters - the ID and the keyword identifier.

The function recreates what the name of the corresponding global variable should be, and then returns its value by evaluating it.

We know that all spaces and hyphens are replaced with underscores when the variables are defined, so we build these same rules into this custom function to help reconstruct the variable name.

And that’s it, pretty simple!  We can use this custom function in a calculation field directly on the Navigation table, and here it is:

We run the custom function, telling it the navigation ID, and the keyword “Navigation”, and it will in turn give us the translated name of the navigation record, in the users currently selected language, brilliant!

That concludes the technical stuff

Congratulations, you made it! Pat yourself on the back!  We hope that wasn’t too confusing for you.  The basic concept of the framework is simply to follow, it’s just setting a bunch of words into global variables and then using those variables in your solution.

The two gotcha areas are value lists, and translating data on records, but we have found ways to solve both of these issues.  In building real world multi-lingual solutions these were the only 2 complications and so we don’t anticipate many other issues….

However…..

There are actually other things you need to consider in building a multi-lingual solution. These are non-technical but you must be aware of them and be thinking about them as you develop.

No two words are created equal

In english, the word “Settings” is 8 characters long. In German - according to Google Translate - it is 17 ! (die Einstellungen)

The implication of this is that if you are placing any text on your layout you must consider the variable widths of words in different languages.  If you place a label to the left of a field, then that label may look fine in English, but in German you may find the label is longer, and overlaps the field.  

You need to be smart about text placement. For labels, consider placing them above the field instead of to the left. By placing them above, you are giving yourself much more room to accommodate labels that are wider or shorter in different languages. 

Don’t rely on an online translator service

For this example file, we used Google Translate. Almost certainly the words are not 100% correct for the German and Spanish translations and for that we apologise. If you are building a real world multi-lingual solution, we could encourage you to enlist the help of someone who speaks the language that you are translating into, to assist with the translations. There is no substitute for someone who knows the language.

Plan your phrase naming convention early

This was touched upon earlier but needs to be reiterated. Make sure you come up with a good naming convention for your phrases early on in development that you are happy with. These serve the basis of your global variable names that you are going to be hard-coding throughout your solution, so make sure you don’t need to change their names down the track!

And finally, have fun!

Building a multi-lingual solution is challenging but incredibly rewarding. There is no sweeter feeling than selecting a different language and seeing your entire solution instantly change before your eyes, it is simply magic. Enjoy the process!

Extra Bonus - Making your Framework even better

If your solution runs server-side, consider making use of this when it comes time to load in your global variables. Depending on the size of your solution, retrieving all of the global variable declarations can be time consuming. This part of the process can quickly be handled by server using the Perform Script on Server script step. Ask server to get you a list of the required variable declarations so that you can load them in locally.  This will help improve the speed of selecting a different language.

The scripts in this example file have PSOS capabilities built into them and are controlled by passing through a parameter to the script to indicate you want to use server-side processes.

Example File

If you made it all the way here without having downloaded and looked at the example file then hats off to you, it must have been a tough read!  You can download the example file below which we would strongly encourage. It’s always better to see something in action and then figure out how it works than to try and read how it works before diving in.

MultiLingual.zip