Internationalization Testing for JSON Formatters

In today's globalized world, software often needs to handle and display data correctly for users from different linguistic and cultural backgrounds. This is the core idea behindInternationalization (i18n) and Localization (l10n). When dealing with structured data formats like JSON, ensuring that numerical, date, time, and currency values are formatted according to locale-specific conventions is crucial. This article explores the importance and strategies for internationalization testing specifically for software components that format JSON data.

What are JSON Formatters and Why Test i18n?

A JSON formatter, in this context, is a piece of software that takes structured data (often in memory as objects or arrays) and converts it into a JSON string. While the JSON specification itself is relatively simple (defining object structure, arrays, strings, numbers, booleans, and null), the *values* within the JSON often represent locale-sensitive data like numbers, dates, times, or currencies.

For example, a number like 12345.67 might be formatted as "12345.67" in a locale like 'en-US', but as "12.345,67" in 'de-DE', or potentially even "12'345.67" in 'fr-CH'. If your JSON formatter doesn't handle these locale-specific differences when converting the internal numerical value to a JSON string, the resulting JSON can be incorrect or misleading when consumed by downstream systems or displayed to users in different locales.

The Goal: Ensure that the JSON output accurately represents the intended data according to the specified or user's locale conventions, especially for numerical, date, time, and currency types.

What Aspects of JSON Formatting Require i18n Testing?

While the structure of JSON ({}, [], `:`, `,`) is universal, the representation of certain data types is locale-dependent:

Number Formatting

• Decimal Separator: Dot (.) vs. Comma (,).
• Thousands Separator: Comma (,), Dot (.), Space (` `), Apostrophe ('), or none.
• Grouping: How digits are grouped (e.g., every three digits, or every four for some South Asian locales).
• Negative Signs: Position and representation.
• Scientific Notation: "e" vs. "E".

Example:

// For number 1234567.89
{
  "en-US": "1,234,567.89",
  "de-DE": "1.234.567,89",
  "fr-FR": "1 234 567,89",
  "hi-IN": "12,34,567.89" // Different grouping
}

Note: The JSON specification states numbers should be represented according to RFC 8259, which uses a dot for the decimal point and no thousands separators in the *value* itself. However, if the formatter is intended to output locale-formatted *strings* containing numbers (e.g., for display purposes), this is where i18n matters. The core issue is how the *formatter* decides to stringify the number based on locale.

Date and Time Formatting

• Format String: Order of year, month, day; use of separators (/, -, ., space).
• Month/Day Names: Full names or abbreviations in local language.
• Time Format: 12-hour vs. 24-hour clock, use of AM/PM.
• Timezone Representation: How timezone offsets or names are included.

Example:

// For Date object representing 2023-10-27 14:30:00 UTC
{
  "en-US": "10/27/2023, 2:30:00 PM", // MM/DD/YYYY, h:mm:ss AM/PM
  "de-DE": "27.10.2023, 14:30:00", // DD.MM.YYYY, HH:mm:ss
  "ja-JP": "2023年10月27日 14時30分00秒" // YYYY年MM月DD日 HH時mm分ss秒
}

Note: ISO 8601 (e.g., "2023-10-27T14:30:00Z") is often preferred for machine-readable JSON as it's locale-agnostic. However, if the JSON is intended for direct display or uses non-standard date formats, i18n testing is essential.

Currency Formatting

• Currency Symbol: Use of $, €, £, ₹, etc.
• Symbol Position: Before or after the number (e.g., $10.50 vs. 10,50 €).
• Spacing: Space between symbol and number.
• Decimal/Thousands Separators: Follows number formatting conventions.

Example:

// For value 10.50 USD, 10.50 EUR, 10.50 JPY
{
  "en-US_USD": "$10.50",
  "de-DE_EUR": "10,50 €",
  "fr-FR_EUR": "10,50 €",
  "ja-JP_JPY": "￥11" // Yen has no decimals
}

Note: Similar to numbers, the JSON value itself might be a simple number (e.g., 10.50), but the formatted string output needs i18n testing if currencies are represented as strings.

String Encoding and Directionality

• Character Sets: Ensuring non-ASCII characters (accented letters, Cyrillic, Arabic, Chinese, etc.) are correctly encoded, ideally using UTF-8.
• Escaping: Proper escaping of special characters within JSON strings (", \, control characters).
• Bidirectional Text (RTL): While JSON itself doesn't dictate display order, if text values contain mixed LTR/RTL content, the formatter shouldn't corrupt the string, and consumers of the JSON must handle display correctly.

Example:

{
  "greeting_fr": "Bonjour le monde",
  "greeting_ru": "Привет мир", // Cyrillic
  "greeting_ar": "مرحبا بالعالم", // Arabic (RTL)
  "quote": "He said, \"Hello!\"" // Escaping quote
}

Note: UTF-8 is the recommended encoding for JSON. Testing involves ensuring characters from various scripts are preserved correctly end-to-end.

Strategies for i18n Testing JSON Formatters

Testing requires a systematic approach focusing on diversity of data and locales.

Test Case Generation

• Locale Data Sets: Create or obtain sets of locale identifiers (e.g., en-US, en-GB, de-DE, fr-FR, es-ES, ja-JP, ar-SA, hi-IN, etc.). Include a diverse range covering different number/date formats, timezones, and scripts.
• Data Value Sets:
  • Numbers: Integers (small, large), decimals (few/many places), negative numbers, zero, scientific notation.
  • Dates/Times: Various dates (start/end of year, leap year), times (AM/PM, midnight, noon), with and without timezones.
  • Currencies: Values with different decimal places, different currency codes (USD, EUR, JPY, etc.).
  • Strings: Include strings with accented characters, characters from various non-Latin scripts (Cyrillic, Arabic, CJK), and strings requiring escaping (quotes, backslashes, control characters).
• Combinations: Test formatting of JSON objects/arrays containing various combinations of these locale-sensitive data types.

Execution and Verification

• Automated Tests:
  • For each locale in your data set, format the test data using the JSON formatter under test, ensuring the locale is correctly applied.
  • Compare the generated JSON string against a pre-defined expected output string for that specific locale and data set.
  • Use assertions to check for correctness of number formats, date strings, currency representations, and string encoding.
• Manual Review: For a subset of critical locales or complex data structures, manually inspect the generated JSON output to catch subtle formatting errors or encoding issues that might be missed by automated pattern matching.
• Round-trip Testing: (If applicable) If the system also parses JSON, test formatting the data and then parsing it back to ensure data integrity is maintained across different locales.
• Platform/Environment Testing: If the formatter runs on different operating systems, JVMs, Node.js versions, etc., verify consistency across these environments, as i18n implementations can sometimes vary.

Common Pitfalls

• Hardcoding Formats: Using fixed patterns (e.g., MM/DD/YYYY) instead of locale-aware formatting APIs.
• Ignoring Locale Settings: Failing to pass or correctly apply the desired locale to the formatting functions.
• Encoding Issues: Outputting non-ASCII characters incorrectly due to wrong encoding (not UTF-8) or improper escaping.
• Locale Fallbacks: Not handling cases where a specific locale's formatting rules are missing, leading to unexpected fallbacks.
• Currency Ambiguity: Outputting just a symbol (e.g., "$") without an explicit currency code if the symbol is used in multiple locales (e.g., USD, CAD, AUD).

Best Practices

• Always use standard i18n libraries provided by your programming language or platform (e.g., Java's java.text.NumberFormat, JavaScript's Intl object, libraries like Moment.js or date-fns with i18n plugins, etc.) for formatting locale-sensitive data before putting it into the JSON string.
• Ensure your formatter outputs JSON strictly as UTF-8.
• Define a clear strategy for which locale to use for formatting (e.g., user's browser locale, a locale specified in the request headers, a default application locale).
• Include a diverse set of locale-specific JSON formatting tests in your automated test suite (unit, integration tests).
• Consider using locale-agnostic formats like ISO 8601 for dates/times and simple numbers/currency codes within JSON values where machine-readability is prioritized over human readability in the raw JSON. Format for display only when presenting to the user.

Conclusion

Internationalization testing for JSON formatters is a vital step in building applications that serve a global audience. By systematically testing how your formatter handles numbers, dates, times, currencies, and strings across various locales, you can ensure the generated JSON is accurate, correctly interpreted by downstream systems, and ultimately provides a better experience for users worldwide. Implementing robust automated tests covering a diverse set of locale data is key to catching and preventing i18n issues in your JSON output.