fix: sort export translations by key name (Sentry TOLGEE-BACKEND-3ED)

[bdshadow]

The StructureModelBuilder requires translations sorted alphabetically by key name path, but the database collation may return them in a different order. Sort in GenericStructuredFileExporter.prepare() to ensure correct ordering regardless of database collation.

Likely triggered by the branching feature (#3246, merged Feb 6) which added a LEFT JOIN on Branch to the export query. The additional join changed the query execution plan, surfacing a collation mismatch between PostgreSQL's locale-aware sorting and Java's byte-by-byte string comparison for keys with punctuation (e.g. "profile.my-goals" vs "profile.my-goals.plan_other").

Summary by CodeRabbit

• Bug Fixes
  • Export validation now detects and prevents collisions between plural key suffixes and existing keys during file export operations. Users receive a clear error message when conflicts are detected, specifying the involved keys and suffix to enable quick resolution.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds plural key suffix collision detection to the export functionality. When pluralsViaSuffixes is enabled, the exporter validates that plural form suffixes don't collide with existing keys, throwing a new exception if conflicts are detected.

Changes

Cohort / File(s)	Summary
Export Collision Detection backend/data/src/main/kotlin/io/tolgee/formats/genericStructuredFile/out/GenericStructuredFileExporter.kt, backend/data/src/test/kotlin/io/tolgee/unit/formats/i18next/out/I18nextFileExporterTest.kt	Adds validation method checkPluralSuffixCollisions() to detect conflicts between plural suffixes and existing keys, with test coverage verifying exception is thrown on collision.
Exception & Message Infrastructure backend/data/src/main/kotlin/io/tolgee/exceptions/ExportCollidingKeysException.kt, backend/data/src/main/kotlin/io/tolgee/constants/Message.kt	Introduces new ExportCollidingKeysException class with pluralKey, collidingKey, and suffix properties, paired with new EXPORT_KEY_PLURAL_SUFFIX_COLLISION message constant.
Frontend Error Handling & Localization webapp/src/translationTools/useErrorTranslation.ts, webapp/src/service/apiSchema.generated.ts, webapp/src/i18n/en.json	Adds error code handling, API schema enumeration, and English localization for the collision error with parameters for affected keys and suffix.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested reviewers

• Anty0

Poem

🐰 A collision we shall catch, before keys clash and match,
With suffixes so sly, we keep your exports dry,
No plural pranks today, they're validated away! ✨

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title claims to sort export translations by key name, but the actual changes implement plural suffix collision detection, not sorting.	Update the title to reflect the actual change: 'fix: detect and throw on plural suffix collisions in exports' or similar, which accurately describes the added collision detection logic.
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bdshadow/fix-nested-structure-export-sorting

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Anty0]

I don't think this is a good way to fix this. This would be a breaking change - the order of keys in the export shouldn't change. I think there are people who depend on sorting being static. Can we solve this without affecting existing sorting?

[coderabbitai]

🧹 Nitpick comments (2)

webapp/src/i18n/en.json (1)

741-741: New key inserted out of alphabetical order

export_key_plural_suffix_collision is placed between two cannot_* keys at line 741, breaking the alphabetical ordering of the file. All other export_* keys appear around lines 929–950. Moving it there keeps the file consistent.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@webapp/src/i18n/en.json` at line 741, The new JSON entry
"export_key_plural_suffix_collision" is out of alphabetical order; cut the
"export_key_plural_suffix_collision" key-value pair from its current location
and insert it with the other "export_*" keys (around the existing export block)
maintaining alphabetical order among export_* entries; ensure you preserve
commas and valid JSON syntax after moving so the file remains parseable.

backend/data/src/main/kotlin/io/tolgee/formats/genericStructuredFile/out/GenericStructuredFileExporter.kt (1)

52-66: Redundant per-language iteration in collision check

translations contains one entry per key per language, so a plural key exported for L languages causes the same name collision check to run L times. Deduplicate by key name first:

♻️ Proposed refactor

 private fun checkPluralSuffixCollisions() {
   val allKeyNames = translations.map { it.key.name }.toSet()
-  translations.filter { it.key.isPlural }.forEach { translation ->
+  val pluralKeyNames = translations.filter { it.key.isPlural }.map { it.key.name }.toSet()
+  for (pluralKeyName in pluralKeyNames) {
     for (suffix in formKeywords) {
-      val suffixedName = "${translation.key.name}_$suffix"
+      val suffixedName = "${pluralKeyName}_$suffix"
       if (suffixedName in allKeyNames) {
         throw ExportCollidingKeysException(
-          pluralKey = translation.key.name,
+          pluralKey = pluralKeyName,
           collidingKey = suffixedName,
           suffix = suffix,
         )
       }
     }
-  }
+  }
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@backend/data/src/main/kotlin/io/tolgee/formats/genericStructuredFile/out/GenericStructuredFileExporter.kt`
around lines 52 - 66, The checkPluralSuffixCollisions function is running the
same collision check once per language because translations contains entries per
key per language; to fix it, deduplicate by key name before iterating: compute
allKeyNames = translations.map { it.key.name }.toSet() as now, then build a set
of pluralKeyNames from translations (e.g. translations.filter { it.key.isPlural
}.map { it.key.name }.toSet()) and iterate that set instead of translations,
checking for each suffix in formKeywords whether "${pluralKey}_$suffix" is in
allKeyNames and throwing ExportCollidingKeysException(pluralKey = pluralKey,
collidingKey = suffixedName, suffix = suffix) when found.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In
`@backend/data/src/main/kotlin/io/tolgee/formats/genericStructuredFile/out/GenericStructuredFileExporter.kt`:
- Around line 52-66: The checkPluralSuffixCollisions function is running the
same collision check once per language because translations contains entries per
key per language; to fix it, deduplicate by key name before iterating: compute
allKeyNames = translations.map { it.key.name }.toSet() as now, then build a set
of pluralKeyNames from translations (e.g. translations.filter { it.key.isPlural
}.map { it.key.name }.toSet()) and iterate that set instead of translations,
checking for each suffix in formKeywords whether "${pluralKey}_$suffix" is in
allKeyNames and throwing ExportCollidingKeysException(pluralKey = pluralKey,
collidingKey = suffixedName, suffix = suffix) when found.

In `@webapp/src/i18n/en.json`:
- Line 741: The new JSON entry "export_key_plural_suffix_collision" is out of
alphabetical order; cut the "export_key_plural_suffix_collision" key-value pair
from its current location and insert it with the other "export_*" keys (around
the existing export block) maintaining alphabetical order among export_*
entries; ensure you preserve commas and valid JSON syntax after moving so the
file remains parseable.

[Anty0]

It's definitely better, but I'm not sure it's an ideal solution. If we miss an edge case, we still end up with an IllegalStateException from throwIfExists. Maybe we can add another exception that just tells the user there is a conflict at the path buildPath(fullPath) if the throw in throwIfExists is reached - I'd just replace the IllegalStateException.

[Anty0]

Shouldn't be part of the changeset.

[Anty0]

We'll deal with the other exception in a separate PR.