A string with gender baked into the English text breaks the moment it reaches Portuguese. "You have 1 new message" needs a different grammatical plural in most Romance and Slavic languages, and a poorly prepared resource file forces the translator to guess whether "1" stays singular or whether the app will actually display "1 messages" to the end user. This is not a style detail. It is a localisation bug that reaches production.
This article covers what separates a resource file that is ready for localisation from one that will generate back-and-forth queries, truncated text and broken plurals once it ships.
Separate text from logic from the start
A common mistake in teams localising for the first time is concatenating strings directly in code. `"User " + name + " has " + count + " messages"` works in English and fails in any language with a different word order or with gender and number agreement. German moves the verb to the end of subordinate clauses. Arabic reads right to left. Neither language respects the fixed order that English-based code assumes.
The correct approach is to use complete strings with named placeholders, not positional ones: `"User {userName} has {messageCount} messages"`. This lets the translator reorder elements according to the target language's grammar without touching the code logic. Frameworks such as ICU MessageFormat, Fluent (Mozilla) and .NET's .resx files already support this pattern natively.
Another source of rework: splitting sentences into fragments that only make sense once reassembled. "Click" + "here" + "to continue" as three separate strings strips the translator of context and often produces a grammatically broken sentence once reassembled. Each string should be a complete unit of meaning.
Plurals: English rules do not apply anywhere else
English has two plural forms: singular and plural. Polish has four, depending on whether the number ends in 1, in 2-4, or in anything else. Arabic has six grammatical plural categories. A resource file built with only `one` and `other` breaks the moment the project needs to support Russian or Arabic.
The CLDR (Common Locale Data Repository) standard, maintained by the Unicode Consortium, defines the plural categories (`zero`, `one`, `two`, `few`, `many`, `other`) that each language actually uses. Most modern internationalisation frameworks (i18next, Fluent, gettext with plural forms, ICU MessageFormat) already implement these categories. Preparing the source file correctly means:
- Never concatenating numbers into fixed strings ("1 item", "2 items" as separate strings)
- Using the plural syntax of the chosen framework, not manual conditionals in the code
- Always including the `other` category as a fallback, even for languages that do not use it for every number
- Testing with values that expose the less obvious categories: 0, 1, 2, 5, 11, 21, 100
A file prepared with these categories from the start saves the translator from having to query every numeric string, and stops the engineering team having to reopen the code after localisation.
Variables, context and text length
Placeholders without context are the second most common cause of localisation errors, after poorly prepared plurals. `{0}` or `{1}` tell the translator nothing about what goes there. Is it a username, a date, a currency value? Naming placeholders descriptively (`{userName}`, `{orderDate}`, `{totalAmount}`) resolves most of the ambiguity at no extra engineering cost.
Context comments in the resource file itself make the difference between a correct translation first time and one that bounces back for revision. A simple comment such as `// Main button on checkout screen, max 20 characters` gives the translator two critical pieces of information: where the string appears and what space constraint it must respect.
This matters particularly in mobile interfaces, where space is limited and German or Finnish can need 30% more characters than English to say the same thing. Teams localising apps for markets such as Angola or Mozambique also face the variable of offline support and network quality, which can require different strategies for loading language resources. The article on mobile app localisation for Angola and Mozambique covers these specific conditions in detail.
File format and workflow
The technical format chosen to export strings directly affects the quality and speed of localisation. The most common ones:
| Format | Typical use | Note |
|---|---|---|
| JSON | Web apps, React, Vue | Easy to automate, no native support for comments |
| .resx | .NET applications | Supports comments and metadata per string |
| .po / .pot | gettext projects, WordPress | Mature standard, good integration with CAT tools |
| XLIFF | Exchange between translation systems | Recommended interchange format for teams working with an external vendor |
| ARB | Flutter | Supports ICU plurals natively |
For projects working with an external translation vendor, XLIFF remains the safest option. It preserves context, comments and placeholders without requiring the translator to edit source code directly. This reduces the risk of someone accidentally deleting a key or altering a placeholder that the application engine expects to find intact.
Teams working with SaaS platforms and continuous release cycles benefit from automating this export, so that every new string created by developers enters the localisation flow without manual intervention. The article on ISO 17100 localisation for SaaS platforms explains how to structure that flow with auditable quality control.
How M21Global handles software files
M21Global works with the file formats most common in software localisation projects, including JSON, .resx, .po and XLIFF, preserving placeholders, CLDR plural categories and context comments throughout the process. For interfaces and the technical documentation tied to software products, the right solution scales with the volume and the criticality of the content, from help catalogues handled with AI-assisted translation to interface strings that call for full human review.
For teams preparing their first localisation cycle, or migrating from a manual process to a structured one, M21Global helps define the export format and naming conventions before the first file handover. Visit the software and technology translation services page and request a technical assessment of your project.
Related Services
Request a free software localisation quote
- Request a free software localisation quote
- Mobile App Localisation Angola Mozambique
- Iso 17100 Localization For Saas Platforms
- A Surprising Amount Of Content Available Online Is Generated By Artificial Intelligence
Frequently Asked Questions
What is CLDR and why does it matter for software localisation?
CLDR (Common Locale Data Repository) is the Unicode Consortium standard that defines plural categories, date and number formats for each language. Preparing the resource file with the correct CLDR categories prevents grammatically incorrect plurals in languages such as Polish, Russian or Arabic.
What is the best file format to send strings to a translation vendor?
XLIFF is generally the safest option for exchange with external vendors, because it preserves context, comments and placeholders without requiring direct editing of source code.
Why is concatenating strings in code a localisation problem?
Concatenating fixed text with variables assumes a word order that does not exist in every language. Using complete strings with named placeholders lets the translator reorder elements according to the target language's grammar.
How many plural forms do I need to support in a multilingual project?
It depends on the target languages: English has two, Polish has four, and Arabic has six. The resource file should follow the CLDR categories for each language in question, rather than assuming the English pattern applies everywhere.
