There are some great libraries that help with i18n in React, but surprisingly little guidance on how to handle i18n end-to-end. This talk will discuss best practices and practical advice for handling translations in React. We will discuss how to extract strings from your code, how to manage translation files, how to think about long-term maintenance of your translations, and even avoiding common pitfalls where single-language developers tend to get stuck.
AI Generated Video Summary
Thanks for joining my talk on end-to-end internationalization. I'll walk you through internationalizing a React app, covering translated strings, currency and date formatting, translator management, and injecting translated strings back into the app. The constants used throughout the app define localization settings and translations. The React Intel library is used for managing translations, and custom functions are created for consistent date and number formatting. The translation process involves extracting strings, using tools like PO Edit, and compiling the translated strings into JSON files for the React app.
1. Introduction to Internationalization
Thanks for joining my talk on end-to-end internationalization. I'm Luke Ersman, a co-founder and software engineer at Gazelle. Gazelle is a SaaS company automating business processes for piano technicians. We have a React web front end, a React native mobile app, and a Rails back end. We market our product globally and needed to fully internationalize it. In this talk, I'll walk you through internationalizing a React app, covering translated strings, currency and date formatting, translator management, and injecting translated strings back into the app. Let's dive into the demo app I created to showcase these concepts.
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.
2. Introduction to Constants
Let's start by looking at the constants. In this section, I'll show you how we've defined the localization settings for currencies, date formats, and number formatting. We also have a list of different locales and translations. These constants will be used throughout the app.
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.
3. Explanation of Higher-Order Components
In this create react app application, the main component is an app component. There are three higher-order components: items context, locale context, and Intel provider. Items context manages the state of the application, while locale context remembers the locale preferences. Intel provider, which uses the React Intel library, manages translations. The setup process involves providing the current locale and a list of translated strings.
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.
4. Exploring Internationalized Strings
In this section, we're pulling the translations for the current locale and setting them in the Intel provider. The shopping list component consists of the header, locale selector, input for adding items, and the list. We use the format message function in React intl to translate strings. This function takes a structure with the string to translate and returns the translated string.
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.
5. Explanation of React Intel
React Intel requires an ID and default message for each string. It also accepts a description to provide context for translators, which is extremely helpful for quality translations.
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.
6. Translation, Localization, and Formatting
At Gazelle, we have two applications, a mobile app, and a web app. We can share strings and translations between them for consistency. React Intel's date and number formatting options are inconsistent across platforms, so I wrote my own functions, Format Currency and Format Date, to ensure consistency and simplify the process.
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.
7. Formatting Dates and Managing Translations
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.
8. Managing Translations and Adding New Strings
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.
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.
9. Pluralization and Translation Process
React Intel allows pluralization based on variables. In the shopping list component, we add an item count beneath the input. It displays the number of items in the component. However, the translation is not yet implemented. To address this, we follow a five-step process. The first step is to code the app using the default language. The second step involves extracting the strings for translation using a script called extract strings.
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.
10. Managing Translations with PO Edit
I use a program called PO Edit to manage get text PO files. It's a fantastic free tool. I open the translations stored in the source locale, edit the PO file in PO Edit, and add the new string. Then, I update the POT file and save it. Finally, I have two PO files with the updated string to send to my translators.
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.
11. Translating and Compiling
Step three involves sending the files to translators for translation. Step four is building the translated strings into JSON files that React can use. Finally, in step five, the React app is recompiled with the new translations, resulting in properly pluralized content in multiple languages.
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.