End-to-end i18n

Thanks for joining me on my talk on end-to-end internationalization. I'm Luke Ersman. I'm one of the co-founders and software engineers at Gazelle. Gazelle is a SaaS company focused on automating business processes for piano technicians. We handle things like scheduling, invoicing, sending automated reminders, all tailored specifically to the piano service industry.

Now for some technical context, we have a React web front end and a React native mobile app that uses Expo. Our back end is a Rails app that provides a GraphQL to these interfaces and we share a lot of code between the web UI and the mobile app, including all of our translated strings. We market our product to piano technicians around the world and we're currently in over 30 countries.

Now early on, one of the technical problems that we ran into was that we needed to fully internationalize our product to serve this global market. This seems like something that would be pretty common, but I was surprised to find how little help there was out there for this. Lots of people have done little bits and pieces of this, but I couldn't find much help for fully internationalizing the app front to back, including all kinds of things, not just translating the strings. The first thing people think of when they think of internationalizing is, you know, translating strings, and this is an important part of it, but it's not the only thing that you need to consider. So in today's talk, I'm going to walk you through how to internationalize a React app from front to end. We're going to cover all aspects, including how to code up the app to handle translated strings, how to localize currency, number, and date formatting, how to extract those strings into something that a translator can use, how to find and manage translators, and finally, how to take those translated strings from the translators back and inject them back into your app.

Now to demonstrate this today, I've created this very simple demo app. This is a shopping list management system where you can type in some items. Here, let me type in bacon for $4.50, and let's say we need to get some lettuce for $1.25, and let's get some tomatoes for $3. Okay. Now when we're out shopping, we can mark some of these items as completed, and you see it shows us the date that we marked it as complete. Now obviously, this is a contrived example. It's not terribly useful, but I did this because it shows all the different components of internationalizing and localizing your app. We have text strings, we have numbers, we have dates, all these things. So in this example, up here is my localization settings. I can change the language to French, I can change the currency to, let's say, where it's in the euro. I can change the location of the currency symbol to be the end — some locales format it that way. I can change the date format, I can change the number format, and you can see all this stuff is instantly localized. Okay, I'm going to change this back to English, so I can actually read it, because I actually don't speak French. Okay, so let me show you — let's take a peek behind the curtain and see how this actually is all coded up. Let me load up my editor here. I use JetBrains as my code editor.

So the first thing I want to show is our constants. So this is where we've defined all of the localization settings that you could use. So we have all the different currencies, and we have some information here on how those currencies need to be formatted. So this way, I can just select USD, and I know that it's two decimal places, it uses the dollar sign symbol, and we have a label here for it. Similarly, I have a list of date formats. Now, these are just format strings that I use to format dates. I have number format information. So there's three different types of number formatting that I support, whether we use commas for separators and dot for decimal separators or not. And then down here, I have the different locales, the different translations and their labels. So for English, it's the ENUS locale. So these are just constants that I've defined that we'll use throughout the app.

Now over here on the, so this is a create react app application. And so the way that that sets it up is that the main component is an app component. And so I've got that here and you can see this is the main content of that component. I have three higher-order components here that I want to explain and then they all wrap our shopping list component.

So the first one here we have is items context. Now this is just what I'm using to manage the state in the application. This is what the list of items that were on our shopping list. In a real world example, this would probably be an API that you would use to store the state and remember it. But for here, just for simplicity, I'm using a context and I'm storing it in memory.

The second one I have here is the locale context. Now this is what remembers our locale preferences. And when I was changing them in the locale selector up there, it was updating this context, which was then providing it to all of the components in the application. And then this third one here is Intel provider. I'm actually using the React Intel library for managing the translations. And React Intel is a wonderful library. I highly recommend it. There are other ones out there, but this is the one that I prefer. And part of the setup process is that you provide this higher-order component. And we tell it what our current locale is. In this case, it was ENUS. Or when I changed it to French, it was FRCA. And then we also provided the list of messages. Now these are the translated strings. This is the end result of the translation process that I provide into here. And those are defined up here. And you can see what this would look like if I go here. This is the end result. We have an ID and we have a translated string. Now that's a peek towards the end of the talk. I'm going to show how we get this.

But for now, we're just pulling those in here and feeding it into this Intel provider. Now notice it's feeding the one for my current locale that I have set. So if I have the French locale set, it's going to pull the French translations in and set those in here.

All right. Let me jump into the shopping list component and show you how this works. But before I do that, let me jump back to the web. And I want to remind you how this what this looks like. The shopping list component has four main components. The top is the header right here. Then we have the locale selector right here. Then we have the input right here where you can add new items. And then we have the list down here. So these are the four main components that make up this application. And then if we go back to the code, you can see these four components here. We have the header. We have the locale selector. We have the item input. And we have our list down here.

Okay. So let's talk about formatting internationalized strings. The way React intl works is they have a component or they have a function called format message that takes a structure that has the string that you want to translate into it. And it returns the translated string. Now it's using that higher order component. You remember I told you the intl provider where we're feeding it in the translated messages. But here I'm defining the translated message and feeding it into the format message function. Now there's other ways you could do it with React intl. They also provide this format message component which is a perfectly valid way to do it. I actually just prefer using this because it just returns a simple string. It makes it easier to use these in other places like that don't accept a component like a placeholder text or things like that. So just for consistency I tend to just use this format message function.

But just know that this other format message is format formatted message component is here as well. Now you'll also notice here I like to define my messages as as as React Intel calls them. I like to define them as constants. And store them all in a centralized repository. In this case it's just a single file called strings.ts. Let me jump to that and you can see what this looks like. So React Intel requires an ID for each string and a default message for each string. Now if you don't have a translation set or if a certain string is not translated, this is what will display. This is also the text that will get sent to the translator so that they for them to translate the string. Now, it also accepts a description, which is some extra information that you can give to translators to give them some context. That's one of the things that I really like about React Intel is it provides this. A lot of the other translation solutions that I've seen out there don't have this context provided. Now I've found that providing this information to the translators is extremely helpful for getting quality translations. It helps them know the nuance of the context. And there's nuance in language sometimes that you need to understand the context of how something is being used in order to translate it properly. So when we define our strings, we don't just type the string that we want translated. We actually take the time to describe how this is used in context to help the translators provide a better translation.

Okay. And you can see I've got all of our strings translated here, or all of our strings defined here as constants that I pull in throughout the application. And so then this is also really helpful at Gazelle because we have, as I mentioned in the intro, we have two applications. We have the mobile app and the web app, and we can share these strings between them and we can share the translations between them. So it helps so we don't have to translate twice, but also so that we have consistency in the wording that we use between both of our apps.

Okay. So now, we've got this translated string. We've passed it to React Intel and it passes back the correct string for whatever language we have selected. Okay. But there's more to internationalizing than just translating strings. So here I've translated a string. But, you know, I've also mentioned the localization settings. So, let me jump into this list item because that's where we have some of the numbers and dates formatted. Before I do that, let me jump back over to the web and just remind you what this looks like. So we have the item name here. We have the currency amount right here, which is a number format, also a currency symbol and we have the date format right here as well.

Okay. So I jump back to the code and this is what that looks like. We've got the checkbox here. We have the note, the description here. We're formatting the currency and then we're formatting the date down here. Now, React Intel does provide some date and number formatting options, but I've actually ended up writing my own for this. The reason for that is I found that React Intel relies on the platform specific internationalization which I have found to be inconsistent across platforms. For example, Android's internationalization is different than iOS's, especially on older versions of Android, and it's also different than some of the internationalization that web browsers provide. So, I ended up just writing my own up. I also found that React Intel's was overly complex for what I needed. I just wanted to pass it in a string and have my localization settings set in one place and not have to think about it again. So, I wrote my own called Format Currency which takes the item amount, the item cost, and takes our localization settings which were defined in that context that I showed you. And you know, pulling that in here from the locale context up here at the top. And similar format date.

It takes the date here and I believe I'm using DayJS here and then I'm passing in the locale settings which has the DayJS formatting string in here to format the date properly. Now I'm not going to go into the implementation of these, they're actually fairly simple. You can pull up my code repo if you're interested and feel free to use those in your own projects. But just know that this works very similar to format message that it takes an item amount, it takes the localization settings and then returns a formatted string in the right format and the same with date.

Okay. Now one other thing to notice here, there's something else special going on with this format message. This is actually taking a variable called date. So what I'm doing here is I'm formatting the date. I'm passing it as a date variable into this completed on formatted message. And then format message is taking that and returning a string with the entire string translated it correctly. So let me jump over to completed on to show you what this looks like. You know, this is just a react Intel message, but it has a variable here and react Intel lets you do variables like this. Now this is nice rather than just appending the date onto the end of the string separately. This is nice because some translations might want the, you know, the way that the language structure where you might do the length, the date first, and then the words, um, you know, different languages, um, put these in different places or, you know, depending on the syntax of the language. So sometimes you want to leave these kinds of variables into the string, that the translators then can move them around where they need to be. It gives them much more flexibility.

Okay. So let's, um, so the end result of all of this, let me jump back to the web again and show you. So the end result of all this is we've got this single string that was done by the format message. It was passed this variable, which is the formatted date context. All right. So now that you understand how the app works, let me show you how to manage the translation process. So at a very high level, this is just a five step process. Um, first you code everything up in JavaScript. So we define our strings using constants with defaults that I showed you. Um, and in general, just make your app work with the default language. Um, next you need to take those strings and extract them from your code into something that you can hand to your translators. In our case at Gazelle, we use get text PO files to hand back and forth, uh, with our translators. One of the reasons I like PO files is it has the ability to show that contextual information as comments to our translators, to help them create better translations. Um, so that's why I do that rather than just passing JSON files back and forth.

And there's also a lot of great tools to help manage PO files for translators. So for this step, we need to extract our new strings and package them up into a PO file for each language. Now I've written a script called extract strings that does this for us. Um, and I've included it in this GitHub repo. Um, it's free to use, feel free to use it for your own projects, but it pulls those, um, uh, those string components, the string constants out of the code and formats them into a get text PO file.

Next, I take that PO file and I hand it to the translator to do their magic. Now there's two ways that you can do this. The cheapest way is to just use Google translate and do it yourself. That's actually what I've done here today for this example, but it's not really a good solution because it often misses nuances of language, but it's free and it's a good place to start. Um, at gazelle, we actually use upwork.com and we hire train, we hire freelance translators. Uh, we use, um, we send them the PO files and it usually takes a few days. Um, but then they send the translated file back to us, uh, with the new translated strings.

The next step that we do is we take that PO file and we build, um, uh, we build it into something that we can import into, um, into our react app. So this is a, I've written another script called build strings that does this, that takes that PO file output and puts it into a plain JavaScript objects that's indexed by the string ID. Then finally we take these plain JavaScript files, um, and inject them back into our code. Okay. That's an overview of this five step process for managing translations. Now I want to show you how this works in real life by adding a new string that needs to be translated. So let me go back over here to the web and what we're going to do is we're going to add another string right down here that tells us how many items we have on our shopping list.

Okay. So let me go back to our code and the first thing we need to do is we need to define this new string. So I'm going to go over here to our string constants file and add the string. Now I'm using jet brains and I have a macro that makes this easy for me. So let me just do this and let's call it item count. Okay. And now I have all of this pre-written over here so I don't have to you don't have to sit here while I'm typing it out. Let me just copy and paste it over here real quick. And then the translation or the actual text of it is going to be here. There we go. Let's remove that new line.

Okay. So now you'll notice that I'm showing something new here. I'm showing pluralization. React Intel lets you pluralize strings as well based on a variable. In this case, this will read different if we have one item versus multiple items and there's a plural s. And this is something that React Intel does for us.

Okay. Let me jump back over to the shopping list component now. Now we're going to add this beneath our item input but before our list. So let me just add this in here. Let's do it as an h2 component. And it was called item count. Actually, MSG item. There it is. And let's oops, close this off. Okay. And then we also had a variable in here. So this was I believe it was called num. And let's pull in, it was items dot length to get the number of items that we have in this component.

Okay, so let's flip back over. And now we've now that it's compiled, we've got the item here, so it says we have three items on our list. But you'll notice though that this is not translated. So if I switch this to French, it's just using the default English because we don't have a French translation or a Japanese translation yet. Okay, so how do we do that? So what we did was the first step in our process, we coded up the app using the default language and just made it work. So now we've got that that was the first step in the five step process. Now the second step is we need to extract this into something that our translators can use. So let me flip over to my terminal. And I'm going to use that script that I wrote called extract strings. Now this reads those messages and puts them into a PO template file here. Now, what we need to do is we take that PO template file, and we update our PO files with this template, which will add the new strings into it.

So I use a program called PO Edit. It's a fantastic free tool out there, and it's great for managing get text PO files. So I'm going to open that, open up these translations. See, we've got it stored in the source locale. Let's open up the French. Let's see, I've got both the JSON file is the built version of this that we pull back into our app. This the one we're going to hand to our translators.

So let me edit the PO file. And this is PO Edit. So up here, it has a list of our strings that need to be translated. And down here is where you actually write the translation. Over here on the side, it's kind of small. I'm not sure if you can see it. This is where we have that contextual string that the translators can use to provide better context for the translation. Okay. Now you'll notice though my new string is not in here because the extract strings function or the script that I wrote pulls it into a POT file, a template file. So in PO Edit, I need to go to update from POT file and pull this in. So here's the POT file. And notice, there we go. So it added my new string into here. And now I'm going to save this. I'm going to close this. And now I can hand that French translation over to my translator.

Let's do the same for the Japanese translation. I'm going to pull that up, go to catalog, update from POT file. And I'm going to pull in my POT file that we created. It's going to add this new string down here that needs to be translated. I'm going to save this. And now I've got these two PO files with my updated string. I'm going to send those to my translators.

Okay, so that was step two. Step three is I send them to my translators, and they translate the files. So let me just pretend that I'm the translator here. I'm going to open this up. I'm going to go to this new string, and I just happen to have the translation over here. Let me copy and paste it. There we go. Let me remove that new line there. And I hit save as the translator, and the translator then would send this file back to me.

Okay, I'm gonna do the same for the Japanese translation. I've got the Japanese one over here. There we go. And let me paste it. Okay, so we've got the Japanese translation, the translator is done with this. Let me add a period on to the end of that. There we go. And the translator sends this back to me. So now I take those files, I put them back into my locale directory. And that was step three where we've gotten the translators to translate the files.

Step four is we need to build these strings into something that React can use. So I'm going to use this other script that I wrote called in bin build strings, which takes those PO files then and turns them into JSON JavaScript files. Let me do that. And now we've updated these are translation files. So if I go to let me just show you what this looks like. That's the JSON file here. And this is where it's just indexed by ID with the translation. And this is what we then pull into our react app that react into will use when we change our translation settings. Okay, so that was the fifth step. I'm sorry, that was the fourth step, we built the strings, and we into this JSON files. Now the fifth step is we need to recompile our react app with these JSON files. Now I'm using create react app, which is automatically running behind the scenes, and it automatically recompiled it. So if I come over here, you will see that I had now have a French translation for this. And I now have a Japanese translation as well. And these are properly pluralized. It says three articles, or however you pronounce that in French, right here. Now there's a lot more that I would like to go into. But I hope that this at least points you in the right direction if you're looking to internationalize your application. Feel free to check out this GitHub repo. You can take the code, use it, feel free to use any of the code in your projects that you want.