How to convert localization files into different formats?
Tags: formatconversions, cli, howto
Published: 2022-04-01 10:00:14

Lucky for you, Localazy comes with the **[Format Conversions](https://localazy.com/docs/general/format-conversions-add-on)** feature you can utilize by downloading our multiplatform [command-line interface (CLI)](https://localazy.com/docs/cli/the-basics) and a vast support of [formats and integrations](https://localazy.com/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](https://localazy.com/blog/guide-preparing-application-for-i18n-l10n-localazy)

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](https://localazy.com/docs/general/format-conversions-add-on) feature.

### Is localizable file conversion with Localazy free or paid?

Format Conversions are available for all users with the [Professional ](https://localazy.com/docs/general/localazy-professional-tier)tier and up.

> See the [pricing page](https://localazy.com/pricing) 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. 🤩

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u2tso52p5pxwufkv43ps.png) 

## 📃 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:

```json
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](https://localazy.com/docs/cli/the-basics).

### 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 `writeKeay`and `readKey` to upload and download the files. For you to have these keys assigned, you must [create a new project](https://localazy.com/my/create) in Localazy and choose the format you'll use as the source for the conversion.

> Remember that the [Format Conversions feature](https://localazy.com/docs/general/format-conversions-add-on) is only available for users with the [Professional tier](https://localazy.com/docs/general/localazy-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
<?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:

```json
"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](https://localazy.com/docs/cli/format-conversions) 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](https://localazy.com/features/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](https://localazy.com/docs/general/connected-projects) in the documentation**

<!--kg-card-begin: html-->

[Connected Apps](https://www.youtube.com/embed/CJXM5jxFY2s)

<!--kg-card-end: html-->

## ✔️ 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](https://localazy.com/dictionary/continuous-integration), consider getting the [Localazy Professional plan](https://localazy.com/pricing) and make your dev life easier with automatic file format conversions. ✌️

### You might also like

*   [Guide: How to prepare your application for i18n & l10n](https://localazy.com/blog/guide-preparing-application-for-i18n-l10n-localazy)
*   [How to localize Go app with go-i18n and Localazy](https://localazy.com/blog/how-to-localize-go-app-with-go-i18n-and-localazy)
*   [Create multi-language newsletters for free using Google Sheets and Localazy](https://localazy.com/blog/create-multi-language-newsletters-free-using-google-sheets-localazy)