Validation Errors Reference

INVALID_UTF8_ENCODING

Severity: ERROR

Description: The file contains invalid UTF-8 encoding. This typically occurs when a file was saved with a different encoding (like Windows-1252 or ISO-8859-1) or contains binary data.

Why This Matters: Invalid encoding prevents the file from being read correctly, which can cause character corruption, display issues in your app, and translation errors. UTF-8 is the standard encoding for modern localization files and ensures proper handling of international characters.

How to Fix:

• Ensure your file is saved with UTF-8 encoding
• In most editors, you can change encoding via "Save As" → "UTF-8"
• Remove any binary or non-text content from the file
• If the file contains special characters, ensure they're properly encoded in UTF-8

Example: A file saved as Windows-1252 containing accented characters will trigger this error.

INVALID_JSON_SYNTAX

Severity: ERROR

Description: The JSON file contains syntax errors that prevent it from being parsed.

Why This Matters: Invalid JSON syntax prevents the file from being parsed, which means translations cannot be loaded into your app. This will cause runtime errors, missing translations, or app crashes when trying to access localized strings.

Common Causes:

• Missing commas between objects
• Trailing commas (not allowed in JSON)
• Unclosed brackets or braces
• Unescaped quotes in string values
• Invalid escape sequences

How to Fix:

• Use a JSON validator or linter to identify syntax errors
• Check the line number reported in the error message
• Ensure all strings are properly quoted
• Remove trailing commas
• Ensure all brackets and braces are properly closed

// ❌ Invalid - trailing comma
{
  "key1": "value1",
  "key2": "value2",
}

// ✅ Valid
{
  "key1": "value1",
  "key2": "value2"
}

INVALID_XML_SYNTAX

Severity: ERROR

Description: The XML file contains syntax errors that prevent it from being parsed.

Why This Matters: Invalid XML syntax prevents Android from reading your strings.xml file, which means your app won't be able to load translations. This can cause build failures, runtime crashes, or missing strings in your Android app.

Common Causes:

• Unclosed XML tags
• Mismatched opening and closing tags
• Invalid characters in XML content
• Missing XML declaration or DOCTYPE
• Improperly escaped special characters (<, >, &)

How to Fix:

• Use an XML validator to identify syntax errors
• Check the line number reported in the error message
• Ensure all tags are properly closed
• Escape special characters: < → <, > → >, & → &
• Verify XML structure matches the expected format for your platform

PARSE_ERROR

Severity: ERROR

Description: A general parsing error occurred while processing the file. This is a catch-all error for parsing issues that don't fit into more specific categories.

Why This Matters: Parse errors prevent the file from being processed, which blocks translation and can cause your app to fail when trying to load localization data. The specific error message will provide details about what went wrong.

How to Fix:

• Review the error message for specific details
• Check the file structure matches the expected format
• Verify the file isn't corrupted
• Ensure the file extension matches the content format

INVALID_STRINGS_SYNTAX

Severity: ERROR

Description: The .strings file contains syntax errors that don't match the expected format.

Why This Matters: Invalid .strings syntax prevents iOS from loading your localization file, which means your app will fall back to the base language or show missing translation keys. This can cause user-facing issues and poor localization experience.

Expected Format:

"key" = "value";

Common Causes:

• Missing semicolon at end of line
• Missing quotes around key or value
• Invalid escape sequences
• Unclosed quotes
• Invalid multiline string syntax

How to Fix:

• Ensure every entry follows the format: "key" = "value";
• Check that all quotes are properly closed
• Escape special characters: \" for quotes, \n for newlines
• For multiline strings, ensure proper continuation syntax

// ❌ Invalid - missing semicolon
"key" = "value"

// ❌ Invalid - missing quotes
key = "value";

// ✅ Valid
"key" = "value";

// ✅ Valid - multiline string
"key" = "Line 1 \
Line 2";

MISSING_STRINGS_DICT_ROOT

Severity: ERROR

Description: The .stringsdict file is missing the root <dict> element.

Why This Matters: Without the root dict element, iOS cannot parse the .stringsdict file, which means plural forms won't work correctly. Your app may crash or display incorrect plural forms when handling numbers.

Expected Structure:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- Your content here -->
</dict>
</plist>

How to Fix:

• Ensure the file starts with proper XML declaration and DOCTYPE
• Wrap all content in a root <dict> element
• Close the <plist> tag properly

MISSING_PLURAL_ONE

Severity: ERROR

Description: A plural entry in a .stringsdict file is missing the required one form.

Why This Matters: iOS requires the one form for proper pluralization. Without it, your app may crash when displaying singular quantities (like "1 item") or display incorrect text. This is especially important for languages that distinguish between singular and plural forms.

Required Plural Forms: iOS plurals require both one and other forms.

How to Fix:

• Add a one key with an appropriate string value
• Ensure the placeholder count matches other forms

// ❌ Invalid - missing "one"
<key>item_count</key>
<dict>
    <key>other</key>
    <string>%ld items</string>
</dict>

// ✅ Valid
<key>item_count</key>
<dict>
    <key>one</key>
    <string>%ld item</string>
    <key>other</key>
    <string>%ld items</string>
</dict>

MISSING_PLURAL_OTHER

Severity: ERROR

Description: A plural entry in a .stringsdict file is missing the required other form.

Why This Matters: The other form is required for all plural quantities that aren't "one" (including zero, two, few, many). Without it, iOS cannot display plural forms correctly, which will cause crashes or incorrect text when displaying multiple items.

Required Plural Forms: iOS plurals require both one and other forms.

How to Fix:

• Add an other key with an appropriate string value
• Ensure the placeholder count matches other forms

INVALID_PLURAL_VALUE_TYPE

Severity: ERROR

Description: A plural entry has an invalid NSStringFormatValueTypeKey value. Plurals require numeric types (like d, f, ld), not object/string types (@).

Why This Matters: Plurals in iOS are designed to work with numeric values (counts, quantities). Using an object/string type (@) is not supported and will cause runtime errors or crashes when iOS tries to format the plural string with a number.

Valid Value Types:

• d - Integer (decimal)
• ld - Long integer
• f - Floating point

Invalid Value Types:

• @ - Object/string (cannot be used with plurals)

How to Fix:

• Change NSStringFormatValueTypeKey from @ to a numeric type
• Update placeholder formats in plural forms to match the value type

// ❌ Invalid - using @ (object) type
<key>NSStringFormatValueTypeKey</key>
<string>@</string>

// ✅ Valid - using d (integer) type
<key>NSStringFormatValueTypeKey</key>
<string>d</string>

MISSING_NSSTRING_LOCALIZED_FORMAT_KEY

Severity: ERROR

Description: A plural entry is missing the required NSStringLocalizedFormatKey.

Why This Matters: The format key tells iOS how to structure the plural string and which variable contains the plural forms. Without it, iOS cannot determine how to format the plural, which will cause crashes or incorrect display.

How to Fix:

• Add the NSStringLocalizedFormatKey with a format string like %#@variable@
• The format string should reference the variable name containing plural forms

MISSING_NSSTRING_FORMAT_SPEC_TYPE_KEY

Severity: ERROR

Description: A plural entry is missing the required NSStringFormatSpecTypeKey.

Why This Matters: This key tells iOS that this is a plural rule type, which is essential for proper pluralization. Without it, iOS won't recognize the entry as a plural and will fail to format it correctly.

How to Fix:

• Add the NSStringFormatSpecTypeKey with value NSStringPluralRuleType

MISSING_NSSTRING_FORMAT_VALUE_TYPE_KEY

Severity: ERROR

Description: A plural entry is missing the required NSStringFormatValueTypeKey.

Why This Matters: This key specifies the data type of the value being pluralized (integer, float, etc.), which iOS needs to correctly format the number in the plural string. Without it, iOS cannot properly format the plural.

How to Fix:

• Add the NSStringFormatValueTypeKey with a numeric type (d, ld, or f)

MISSING_STRING_NAME

Severity: ERROR

Description: A <string> element is missing the required name attribute.

Why This Matters: The name attribute is the identifier used to reference the string in your Android code. Without it, you cannot access the string resource, which will cause build errors or runtime crashes when trying to use that string.

How to Fix:

• Add a name attribute to every <string> element
• The name should be a valid Android resource identifier

<!-- ❌ Invalid - missing name attribute -->
<string>Hello World</string>

<!-- ✅ Valid -->
<string name="hello_world">Hello World</string>

MISSING_PLURAL_NAME

Severity: ERROR

Description: A <plurals> element is missing the required name attribute.

Why This Matters: The name attribute is required to reference the plural resource in your Android code. Without it, you cannot use the plural in your app, which will cause build errors or runtime crashes.

How to Fix:

• Add a name attribute to every <plurals> element

MISSING_PLURAL_ONE (React Native)

Severity: ERROR

Description: An i18next-style plural object is missing the required _one key.

Why This Matters: i18next requires the _one form for proper pluralization. Without it, your React Native app may crash when displaying singular quantities or show incorrect text. This is essential for languages that distinguish between singular and plural forms.

Required Plural Forms: i18next plurals require both _one and _other forms.

How to Fix:

• Add a _one key with an appropriate string value
• Ensure the placeholder count matches other forms

// ❌ Invalid - missing "_one"
{
  "item_count": {
    "_other": "{{count}} items"
  }
}

// ✅ Valid
{
  "item_count": {
    "_one": "{{count}} item",
    "_other": "{{count}} items"
  }
}

MISSING_PLURAL_OTHER (React Native)

Severity: ERROR

Description: An i18next-style plural object is missing the required _other key.

Why This Matters: The _other form is required for all plural quantities (zero, two, few, many, etc.). Without it, i18next cannot display plural forms correctly, which will cause crashes or incorrect text when displaying multiple items in your React Native app.

How to Fix:

• Add an _other key with an appropriate string value
• Ensure the placeholder count matches other forms

Placeholder & ICU structure (INVALID_PLACEHOLDER_FORMAT / TRANSLATION_BROKEN_INTERPOLATION)

Severity: ERROR

Description: A translated ICU message must (1) reference the same set of named arguments as the source, (2) keep the required other case in every plural/select, and (3) have balanced braces.

Why This Matters: flutter gen-l10n fails to build if an ICU message is malformed, and a renamed or dropped argument means the value your code passes in never renders. These are caught before the file reaches your project.

How to Fix:

• Keep every argument name from the source (e.g. don't translate {userName} into {nombreUsuario})
• Keep an other{…} branch in each plural/select
• Balance every { with a }

// ❌ Invalid - argument renamed, and the required "other" case dropped
"greeting": "Hola {nombre}",
"itemCount": "{count, plural, one{1 artículo}}"

// ✅ Valid - same argument names, "other" preserved
"greeting": "Hola {name}",
"itemCount": "{count, plural, one{1 artículo} other{{count} artículos}}"

Plural categories may differ by language (this is not an error)

Good to know: ICU plural categories are language-specific, and we deliberately do not force the source's categories onto a translation. English uses one/other; Polish needs one/few/many/other; Japanese uses only other. A correct Polish translation that adds few and many — or a Japanese one that collapses to just other — is valid and will not be flagged.

The only plural requirement we enforce is the one ICU itself mandates: an other case must be present. Forcing category parity between source and target is a common localization bug in naive tools; matching each language's CLDR plural rules is the correct behavior.

// Source (English)
"itemCount": "{count, plural, one{1 item} other{{count} items}}"

// ✅ Valid Polish translation - adds "few" and "many" (CLDR-correct, not an error)
"itemCount": "{count, plural, one{1 przedmiot} few{{count} przedmioty} many{{count} przedmiotów} other{{count} przedmiotu}}"

Messages using ICU quote-escaping are skipped

Good to know: If a message uses ICU single-quote escaping (e.g. Flutter's use-escaping: true to render a literal brace), the ICU checks above are skipped for that message rather than risk a false positive. JSON syntax, empty-value, and unsafe-character checks still apply. This is a rare, off-by-default Flutter setting.

INVALID_PLACEHOLDER_FORMAT

Severity: ERROR

Description: A placeholder doesn't match the allowed format for the platform.

Why This Matters: Invalid placeholder formats will cause runtime errors when your app tries to format strings with variables. The app may crash, display incorrect text, or fail to substitute values properly. Each platform has specific placeholder syntax requirements that must be followed.

iOS Valid Placeholders:

• %@ - Object/string
• %d - Integer
• %ld - Long integer
• %f - Floating point
• %c - Character
• %s - C string
• With modifiers: %5d, %.2f, %+d
• Positional: %1$d, %2$@, %8$3.2f

Android Valid Placeholders:

• %d - Integer
• %s - String
• %f - Floating point
• Positional: %1$d, %2$s

React Native (i18next) Valid Placeholders:

• {{variable}} - Variable interpolation
• Variable names can contain: letters, numbers, underscores, dots, hyphens

How to Fix:

• Ensure placeholders match the platform's format
• Check for typos in placeholder syntax
• Verify you're using the correct placeholder type for your data

// ❌ Invalid iOS placeholder
"message": "Hello %x world"  // %x is not valid

// ✅ Valid iOS placeholder
"message": "Hello %@ world"

// ❌ Invalid i18next placeholder
"message": "Hello {{variable name}}"  // spaces not allowed

// ✅ Valid i18next placeholder
"message": "Hello {{variable_name}}"

PLACEHOLDER_COUNT_MISMATCH

Severity: ERROR

Description: Different plural forms have different numbers of placeholders. All plural forms must have the same placeholder count.

Why This Matters: When a plural is used, the same number of arguments must be provided regardless of which form is selected. Mismatched counts indicate a structural error.

How to Fix:

• Count placeholders in each plural form
• Ensure all forms have the same number
• Add missing placeholders or remove extra ones to match

// ❌ Invalid - mismatch: zero has 0, one has 1, other has 1
{
  "zero": "No matches",
  "one": "%ld match",
  "other": "%ld matches"
}

// ✅ Valid - all forms have 1 placeholder
{
  "zero": "%ld matches",  // Fixed: added placeholder
  "one": "%ld match",
  "other": "%ld matches"
}

// ✅ Alternative fix - remove placeholder from other forms
{
  "zero": "No matches",
  "one": "One match",  // Fixed: removed placeholder
  "other": "Many matches"  // Fixed: removed placeholder
}

BASE_MISSING_PLURAL_FORM

Severity: ERROR

Description: A base plural string is missing plural forms required by one or more of your project's target languages.

Why This Matters: Different languages require different plural forms. For example, Polish requires one, few, many, and other, while English only requires one and other. If your base string only has English forms but your project targets Polish, translations will be incomplete and may cause runtime errors or incorrect pluralization in your app.

Common Scenarios:

• Base language is English (needs: one, other) but project targets Polish (needs: one, few, many, other)
• Base language is English but project targets Russian, Arabic, or other languages with complex plural rules

How to Fix:

• Add the missing plural forms to your base string
• Use the "other" form as a template for missing forms initially
• Review the error message to see which forms are missing for which target languages
• Consider adding all commonly needed forms (zero, one, two, few, many, other) to your base strings to support all languages

// ❌ Invalid - missing "few" and "many" required for Polish
{
  "one": "1 item",
  "other": "%d items"
}

// ✅ Valid - includes all forms required for Polish
{
  "one": "1 item",
  "few": "%d items",    // Added for Polish
  "many": "%d items",   // Added for Polish
  "other": "%d items"
}

TRANSLATION_MISSING_PLURAL_FORM

Severity: ERROR

Description: A translation is missing plural forms that exist in the base string.

Why This Matters: Translations must maintain structural consistency with the base string. If the base has certain plural forms, the translation must have them too, otherwise your app may crash or display incorrect text when accessing those forms. This ensures that all plural forms are properly translated and available in all languages.

Common Causes:

• Translation was manually edited and some forms were accidentally removed
• Translation was created from an incomplete base string
• Translation file was corrupted or partially uploaded

How to Fix:

• Add the missing plural forms to the translation
• Ensure all forms from the base string are present in the translation
• Re-translate the string if needed to ensure all forms are included

// Base string
{
  "one": "1 item",
  "other": "%d items"
}

// ❌ Invalid translation - missing "one" form
{
  "other": "%d artículos"
}

// ✅ Valid translation - all base forms present
{
  "one": "1 artículo",
  "other": "%d artículos"
}

TRANSLATION_MISSING_LANGUAGE_PLURAL_FORM

Severity: ERROR

Description: A translation is missing plural forms required by the target language's pluralization rules.

Why This Matters: Each language has specific plural forms it requires based on Unicode CLDR plural rules. For example, Polish requires one, few, many, and other. If a translation is missing these required forms, your app will crash or display incorrect pluralization when using that language. This is especially critical for languages with complex plural rules.

Language-Specific Requirements:

• Simple languages (English, Spanish, French, etc.): Require one and other
• Complex languages (Polish, Russian, etc.): Require one, few, many, and other
• No singular languages (Japanese, Chinese, etc.): Require only other
• Very complex languages (Arabic): Require zero, one, two, few, many, and other

How to Fix:

• Add the missing plural forms required by the target language
• Use appropriate translations for each form based on the language's pluralization rules
• Re-translate the string if needed to ensure all required forms are included
• Review the error message to see which specific forms are missing

// Base string (English - only needs one/other)
{
  "one": "1 item",
  "other": "%d items"
}

// ❌ Invalid Polish translation - missing "few" and "many"
{
  "one": "1 element",
  "other": "%d elementów"
}

// ✅ Valid Polish translation - all required forms present
{
  "one": "1 element",
  "few": "%d elementy",      // Required for Polish
  "many": "%d elementów",    // Required for Polish
  "other": "%d elementów"
}