Lab 3.2: ICU Plural Syntax & CLDR Matching

Objective

In this hands-on lab, you will act as a localization engineer refactoring broken, hardcoded plural logic into standardized ICU MessageFormat. You will transform naive ternary expressions into locale-aware ICU assets, implement multi-category CLDR plural rules for Slavic target locales (Polish), and validate brace symmetry and fallback rules using Visual Studio Code.

Required Setup & Prerequisites

• Editor: Visual Studio Code installed.

• Working Directory: Open your loc_lab working directory in VS Code.

Step-by-Step Instructions

Step 1: Analyze the Legacy Hardcoded Source

Imagine a developer handed you a legacy string file where plural logic was attempted using string concatenation and naive English conditionals.

1. Open VS Code and navigate to assets/loc/software/.

2. Create a file named legacy_plurals_en.json and paste:

   JSON

   json
   {
     "file_deleted": "File deleted successfully.",
     "files_deleted": " files deleted successfully.",
     "item_count_label": "You have "
   }

3. Identify the Architecture Defects:

   • files_deleted expects the code to glue a number to the front (count + " files deleted successfully."), forcing English word order.

   • A Polish translator cannot translate " files deleted successfully." in isolation because numbers ending in 2, 3, or 4 require pliki, while numbers ending in 5–20 require plików.

Step 2: Re-Architect Source Asset using ICU MessageFormat (en_clean.json)

Convert the hardcoded fragments into a unified, atomic ICU plural block with an explicit =0 exact match for clean UI copy.

1. In assets/loc/software/, create icu_plurals_en.json.

2. Write the standard English ICU plural structure using the variable name itemCount:

JSON

json
{
  "delete_status": "{itemCount, plural, =0 {No files deleted.} one {# file deleted successfully.} other {# files deleted successfully.}}"
}

Key Observations:

• =0 overrides grammatical plurals to render "No files deleted." when itemCount is zero.

• one handles single items (# file deleted...).

• other serves as the mandatory fallback for all other numbers.

• # dynamically prints the value of itemCount.

1. Save icu_plurals_en.json.

Step 3: Localize into Polish (icu_plurals_pl.json)

In Polish (pl-PL), plural logic requires 4 CLDR categories: one, few, many, and other.

1. In the same folder, create icu_plurals_pl.json.

2. Construct the localized ICU block using the correct Polish grammatical forms:

   • one (1 item): 1 plik

   • few (numbers ending in 2–4, except 12–14): # pliki

   • many (numbers ending in 0, 5–9, or 11–14): # plików

   • other (fractions/fallbacks): # pliku

JSON

json
{
  "delete_status": "{itemCount, plural, =0 {Brak usuniętych plików.} one {# plik został pomyślnie usunięty.} few {# pliki zostały pomyślnie usunięte.} many {# plików zostało pomyślnie usuniętych.} other {# pliku zostało pomyślnie usuniętych.}}"
}

1. Save icu_plurals_pl.json.

Step 4: Validate ICU Syntax and Brace Balance in VS Code

A single missing or misplaced brace in ICU MessageFormat causes runtime parser exceptions.

1. Open icu_plurals_pl.json in VS Code.

2. Place your cursor right next to the opening brace { after "delete_status": ".

3. Notice that VS Code automatically highlights its matching closing brace } at the end of the line.

4. Verify the 3 Nested Layers of Braces:

   • Layer 1 (Outer String): "{itemCount, ... }"

   • Layer 2 (Category Blocks): one { ... }, few { ... }, many { ... }, other { ... }

   • Layer 3 (Variables inside blocks if used instead of #): {itemCount}

5. Verify that the other category is explicitly declared (required in all locales).

Self-Verification Checklist

Check your ICU assets against these production criteria:

• [ ] icu_plurals_en.json uses valid ICU syntax with an explicit =0 match and # count shorthand.

• [ ] icu_plurals_pl.json includes all required Polish CLDR categories (one, few, many, other).

• [ ] Every opening brace { has a corresponding closing brace } (zero syntax errors).

• [ ] Both assets are saved in valid UTF-8 encoding.