How to convert localization files into different formats?

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.

❓ What are localizable file format conversions?

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. 🤩

📃 Sample use case of converting localizable files into different formats

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 XML
arb - Convert to Flutter ARB
ini - Convert to INI
ini-multilingual - Convert to multilingual INI
ios-strings - Convert to iOS’s .strings
ios-stringsdict - Convert to iOS’s .stringsdict
json - Convert to JSON
json-mozilla - Convert to Mozilla i18n JSON
json-multilingual - Convert to multilingual JSON
yaml - Convert to YAML
yaml-multilingual - Convert to multilingual YAML
yaml-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. ✌️

Blog