📝 docs(api): document the CLDR plural rules on the v3 languages endpoint

[mauretto78]

Summary

GET /api/v3/languages returns a fourth field per language, plurals, carrying the CLDR
plural rules that the plural and selectordinal arguments of an ICU message select on. The
spec described only code, name and direction, and carried no example response at all — so
Swagger UI synthesised a {"code": "string", …} placeholder out of the schema.

This documents the field, replaces that placeholder with the real payload, and rewords the
endpoint summary and description. Documentation only: no PHP, JS or SQL is touched.

Type

• feat — new user-facing feature
• fix — bug fix
• refactor — restructure without behavior change
• chore — build, deps, config, docs
• perf — performance improvement
• test — test coverage

Changes

File	Change
public/api/swagger-source.json → paths./api/v3/languages.get	Reworded summary and description; 200 gains an examples block holding the real payload for ar-SA and it-IT; response description re-cased from Languages List to sentence case
public/api/swagger-source.json → definitions.Language	New plurals property ($ref + x-nullable); per-field example values; code description corrected from Rfc code to BCP 47 language+region code
public/api/swagger-source.json → definitions.Languages	Records that the array is sorted alphabetically by name
public/api/swagger-source.json → definitions.LanguagePluralRules (new)	name, isoCode, cardinal, ordinal — the shape of LanguageRulesFragment
public/api/swagger-source.json → definitions.PluralCategoryRule (new)	category, rule, human_rule, example — the shape of CategoryFragment, with the zero/one/two/few/many/other enum

Testing

• vendor/bin/phpunit --exclude-group=ExternalServices --no-coverage passes
• ./vendor/bin/phpstan passes (0 errors, with baseline)
• Manual testing performed (describe below)
• New tests added for changed behavior
• Regression tests added for bug fixes

The spec was checked against the code that actually builds the response, not against the old
prose. /api/v3/languages is routed at lib/Routes/api_v3_routes.php:243 to
Controller\API\V2\SupportedLanguagesController::index, and the entry shape comes from the
matecat/icu-intl package (Locales\Languages::buildEnabledLanguageList() plus
injectPluralRules(), serialised by the LanguageRulesFragment and CategoryFragment DTOs).

Verification performed:

• The file still parses as JSON and every $ref in it resolves — no dangling references, and
  definitions.Language now carries all four properties.
• Both documented example entries compare equal, key for key, to what
  vendor/matecat/icu-intl/src/resources/pluralRules.json and supported_langs.json produce
  for ar-SA and it-IT, so the example cannot drift from the payload silently.
• ar-SA was chosen because it is the only shape that exercises all six cardinal categories
  and an RTL direction; it-IT adds a non-trivial many cardinal and a two-category ordinal.

No PHP or JS changed, so phpunit, phpstan and yarn test are untouched by this PR and were
not re-run. npx prettier --check still flags swagger-source.json, but it flags the file
unmodified too (confirmed by stashing) — pre-existing, and --write would reformat all 230 KB.

AI Disclosure

• No AI tools were used in this PR
• AI tools were used — name the agent/tool below

Claude Code (claude-opus-5)

Notes

Two facts about the payload are worth a reviewer's eye, because both are documented as they
really behave rather than as one might expect:

• plurals.isoCode is the base ISO code, so regional variants share one rule set
  (en-US → en); pt_pt is currently the only rule set defined per region.
• Consequently plurals.name names whichever variant the shared set was built from — en-US
  reports plurals.name: "English (Australia)". The LanguagePluralRules.name description says
  so explicitly, and the examples deliberately use it-IT and ar-SA, where the two names
  coincide, so the example itself does not look like a bug.
• plurals is typed LanguageRulesFragment|null in the package, so it is marked
  x-nullable: true even though no currently enabled language resolves to null.

Out of scope, flagged for later: the identical payload is also served at /api/v2/languages and
/api/app/languages (the route the React app actually calls), and neither appears in the spec.
public/api/swagger-source.js is a drifted, unread copy of the spec and was left alone.

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1216793059377403

[github-actions]

🧪 Test-Guard Report

✅ PASS — All changed source files have adequate test coverage.

Coverage Analysis: ⏭️ SKIP

No source files to analyze — all changed files are tests or excluded.

Test File Matching: ✅ PASS

No source files to check

Per-File Evaluation: ✅ PASS

No source files to evaluate.

Result: ✅ PASS