Lucky for you, Localazy comes with the Format Conversions feature you can utilize by downloading our multiplatform command-line interface (CLI) and a vast support of formats and integrations.
To localize a project, we need to keep everything the user sees external to ensure that whenever we need to adapt the project to different areas/regions/countries, we won't have to fiddle with the code every time we want to add a new locale.
Read our guide on How to prepare your app for i18n & l10n
The text is how we mainly communicate with the user, and so we need to keep the strings outside the code, stored in a file with a determined format. This format depends on the framework/library we are using, as different frameworks/libraries have specific structures they work with.
So, what will happen if we want to adapt our product to new platforms or integrate new tools and utilize different localizable file formats? Will your files be unusable? No, Localazy got your back; we'll convert the file formats for you with our Format Conversions feature.
Is localizable file conversion with Localazy free or paid?
Format Conversions are available for all users with the Professional tier and up.
See the pricing page for options
It will pay off with the first single conversion you perform—no limitations as of formats, number of operations, or conversion data volume. Once you make it a part of your workflow and automate converting localizable files, your dev life will get easier, we can guarantee that. 🤩
To demonstrate the feature, we'll create a YAML file, and we'll do an example conversion to JSON. These are only two examples from the variety of formats available for conversion; you can convert:
android - Convert to Android XMLarb - Convert to Flutter ARBini - Convert to INIini-multilingual - Convert to multilingual INIios-strings - Convert to iOS’s .stringsios-stringsdict - Convert to iOS’s .stringsdictjson - Convert to JSONjson-mozilla - Convert to Mozilla i18n JSONjson-multilingual - Convert to multilingual JSONyaml - Convert to YAMLyaml-multilingual - Convert to multilingual YAMLyaml-rails - Convert to Rails i18n YAML
Create your file
The file we create contains the following strings:
calendar:
one: "Calendar"
other: "Calendars"
field:
one: "Field"
other: "Fields"
hello_localazy: "Hello Localazy!"
We'll name the file as en.yml. So now that we have a localizable file, what will we do?
Create a directory structure
For this example, we'll create a directory structure with the following layout:
.
├── locales
│ └── en.yml
├── converted
├── localazy.exe
└── localazy.json
The locales folder is where we will keep the file we want to convert, and in the converted folder, we will store the converted files. All of this will have to be configured in our localazy.json file.
The localazy.exe file is the Localazy CLI; if you use a different OS, you might not have to have it downloaded and stored here.
For more information about the CLI, check The Basics – Localazy.
Set up your Localazy configuration
With this done, we can start populating our localazy.json file with the following configuration:
{
"writeKey": "your-write-key",
"readKey": "your-read-key",
"upload": {
"type": "yaml",
"files": "/locales/en.yml"
},
"conversion": {
"actions":
{
"type": "json",
"output": "converted/${lang}.json"
}
}
}
We didn't add a download section to the localazy.json configuration file because we are simply doing file conversions for now and not translations.
If you're familiar with our CLI, you know that we use writeKeayand readKey to upload and download the files. For you to have these keys assigned, you must create a new project in Localazy and choose the format you'll use as the source for the conversion.
Remember that the Format Conversions feature is only available for users with the Professional tier and up, meaning that the following steps will not function if you are on the Free plan and the feature is locked. However, you can activate a 7-day trial of the Professional plan to try everything out.
Conversion
When you have your keys ready, just add them to the localazy.json file, and we'll now use the Localazy CLI to upload the strings and then download the converted file. Just execute:
localazy upload - This will upload the strings to our server, where all the magic happens.
localazy download - This will download the converted format file.
Your folder layout will now look like this:
.
├── locales
│ └── en.yml
├── converted
| └── en.json
├── localazy.exe
└── localazy.json
As you can see, inside the converted folder, there's the converted file. This file will now have the .json extension and will look like this:
{
"calendar": {
"one": "Calendar",
"other": "Calendars"
},
"field": {
"one": "Field",
"other": "Fields"
},
"hello_localazy": "Hello Localazy!"
}
📏 Structured keys flattening
In some cases, we encounter a localizable file with multiple levels; for example, the JSON file we have just converted.
We cannot transfer the same level structure to some formats, say: Android XML as an example. Depending on the situation, Format Conversions offer multiple key flattening options like:
- Don't flatten structured keys;
- Flatten structured keys with a dot ( . );
- Flatten structured keys with an underscore ( _ );
- Flatten structured keys with a dash ( - )
The default output result of the conversion to Android would then be:
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
<string name="hello_localazy">"Hello Localazy!"</string>
<string name="calendar_one">"Calendar"</string>
<string name="calendar_other">"Calendars"</string>
<string name="field_one">"Field"</string>
<string name="field_other">"Fields"</string>
</resources>
If you would like to specify the flattening, all you have to do is add:
"actions":
… other specifications …
{
"params": {
"flatten_keys": "dot"
}
}
Keep in mind all the options and specifications are dependent on the formats you're converting.
See Format Conversions CLI documentation for all the available options you can use to configure your conversions.
🔌 Do you have multiple projects? Try Connected Projects!
Format Conversions are perfect for 1:1 conversion of your files. But sometimes, your product might consist of multiple sub-projects that can contain files that are very similar, but not identical, so conversion wouldn't be a viable option.
In this case, you should consider setting up the Connected Projects feature included with your Professional plan, that is designed to help you with seamless translation sharing between your own projects.
Connected Projects empower you to translate your content only once and then let Localazy handle the rest. Perfect for multiplatform development or a portfolio of similar apps that share same texts.
Once you set everything up, Localazy keeps your translations in sync without any extra steps needed, speeds up the translation process by automatically approving matching texts, and allows all projects to tap into one central glossary.
Read more about Connected Projects in the documentation
Connected Apps
✔️ Conclusion
We hope you liked this short tutorial on converting localizable file formats. If file conversion is something that you are battling with in your CI/CD, consider getting the Localazy Professional plan and make your dev life easier with automatic file format conversions. ✌️
You might also like
