How to Manage Resource Files for Effective Internationalization & Localization

Resource files are a crucial component of software localization. If you’re a developer or work in localization, you’ve probably heard of them. But for those who haven’t, don’t worry – we’ll break it down

What’s a resource file?

A resource file stores all the user-facing text in an app or website. Instead of hardcoding phrases like “Click here” or “Welcome” directly into your code, you put them in a separate file. This file is basically a list of labels and their corresponding text in different languages.

For example:

WELCOME_MESSAGE = Welcome

CLICK_HERE = Click here

Then, for other languages, you create similar files with the same labels but translated text:

WELCOME_MESSAGE = Bienvenue

CLICK_HERE = Cliquez ici

These files come in different formats depending on what programming language or framework you’re using. Java uses .properties files, .NET uses .resx, and web apps often use JSON.

Why bother with resource files?

You might be wondering why you’d go through the trouble of setting up these files. Well, there are a few good reasons:

1. It keeps your code clean. Developers can focus on functionality without worrying about text.
2. Translators can work directly with these files without touching your code.
3. Adding new languages is much easier – just create a new resource file.
4. You can update text across your entire app by changing one file.
5. It helps maintain consistency in your translations.

By using resource files, you’re setting yourself up for success when it comes to making your app available in multiple languages. Although it may seem like extra work initially, the benefits are significant over time.

Common File Formats for Resource Files

As we already mentioned, different programming languages handle resource files in their own formats. How to denote locales, how to pass locales in the application execution path, and how to fall back on the default locale when a given locale resource is not found.

Here are some common examples:

• Java: standard resource files end in .properties? and are named based on the target locales, such as resources.properties for the source locale and resources_fr.properties for the French file.
• JavaScript: Often uses JSON files to store localized content.
• Android: end in xml (e.g. strings.xml) and are located under directories named “res/values” for the source locale, and “values-fr” for the French version of the files under that directory.

Following these standard file formats, will help developers streamline the internationalization (i18n) process and make it easier to manage localization (l10n).

Challenges with Non-Standard Resource Files

While standard formats simplify localization, some developers use non-standard methods to store resource files. Here are some real-life examples:

Using JSON files with locale as the root key

In this case, JSON files are named with locales, which means the filename itself indicates the language or region (e.g., en.json for English). However, inside the file, the locale is used as the root key. This means that all strings or data in the file are nested under the locale identifier within the file structure.

Instead of:

This structure can make it harder to manage if there are multiple locales in one file, as it requires additional handling when extracting translations.

Storing all locales in a single YAML file

At build time the file is split into multiple YAML files, each representing a specific locale. These files are then converted into CSV format and sent for translation. Once the translations are complete, the CSV files are returned, reprocessed back into their respective formats (YAML), and then pushed into a database to update the localized content.

This method allows the central management of multiple locales but adds complexity during the translation and build process.

Create multiple YAML files for different locales

During the build time, these YAML files are combined into a single read-only JSON file that contains all the locales’ data. This can cause the following problems:

1. Loss of Flexibility: A single read-only file makes it harder to update or modify individual locale data without re-generating the entire file.
2. Size and Performance Issues: Large JSON files containing all locales may slow down load times or increase memory usage, especially for large-scale applications.
3. Error Handling: If there’s an error with one locale, the entire file may become unusable, making debugging more complex.

Storing resource files in deeply nested paths

Instead of placing the resource files directly in a directory tied to the locale (e.g., en/resources.json for English), they are stored in a more complex directory structure, located “somewhere below,” such as en/my/deep/path/to/the/resources.json.?

This approach complicates the organization and retrieval of localization files, making it harder to manage and track them, as the directory structure is unnecessarily deep or non-standard.

Misuse of YAML by formatting it like XML?

Instead of following proper YAML syntax it is formatted like XML. This incorrect approach adds unnecessary complexity.

The correct approach simplifies it by using direct key-value pairs:

Using the same naming for resource files

Multiple files, which are meant to store different types of content or resources, all share the same filename, like “en.json” for English content. This causes confusion and difficulty in managing these files because it’s hard to distinguish between them without looking at the directory path. Best practices recommend giving each file a unique, descriptive name (e.g., menu_en.json or homepage_en.json) to improve clarity and organization.

These “creative” approaches in resource file management can lead to additional work for both developers and localization teams. It may require creating custom scripts, managing complex directory structures, and developing specialized workflows for translation and file validation. This can increase the risk of errors and slow down the localization process and as a consequence, the development cycle.

Best Practices for Managing Resource Files

To make the i18n and l10n processes smoother, follow these best practices:

1. Use Programming Framework-Recommended File Formats: Stick to the standard file formats for your programming environment (e.g., .resx for .NET, JSON for JavaScript, or .properties for Java). This simplifies both development and localization workflows.
2. One File per Locale: Ensure each locale has its own dedicated resource file. This makes it easier to add or remove languages without affecting other locales.
3. Follow ISO Naming Conventions: Use standard naming conventions such as ISO 639 for languages (e.g., en_US for U.S. English or fr_FR for French). This ensures consistency and helps both developers and localization teams quickly identify and work with the correct locale files.
4. Simplify the Process: Don’t overcomplicate things. If your source code is written in JSON, use JSON for translations instead of creating unnecessary conversions. Keeping the same format from development to localization avoids complexity and errors.
5. Unique File Naming: Ensure each file has a unique, descriptive name to avoid confusion. Avoid having 200 files named “en.json” scattered across directories. This improves file organization and tracking.
6. Consistent Locale Naming: Use the same locale structure across all resource files in your repository. For example, always follow the pattern language/country/variant (optional) for all files to prevent inconsistency and confusion.

Lingoport offers solutions that can help automate and streamline your i18n and l10n processes, ensuring your software is ready for global markets. If you need any support contact us. We can help you go global at the speed of development.