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

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").

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## 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.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: bdshadow

backend/data/src/main/kotlin/io/tolgee/constants/Message.kt

@@ -325,6 +325,7 @@ enum class Message {
   BRANCH_MERGE_CONFLICTS_NOT_RESOLVED,
   BRANCH_MERGE_ALREADY_MERGED,
   BRANCHING_NOT_ENABLED_FOR_PROJECT,
+  EXPORT_KEY_PLURAL_SUFFIX_COLLISION,
   ;
 
   val code: String

backend/data/src/main/kotlin/io/tolgee/exceptions/ExportCollidingKeysException.kt

@@ -0,0 +1,12 @@
+package io.tolgee.exceptions
+
+import io.tolgee.constants.Message
+
+class ExportCollidingKeysException(
+  val pluralKey: String,
+  val collidingKey: String,
+  val suffix: String,
+) : BadRequestException(
+    Message.EXPORT_KEY_PLURAL_SUFFIX_COLLISION,
+    listOf(pluralKey, collidingKey, suffix),
+  )

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

@@ -2,8 +2,10 @@ package io.tolgee.formats.genericStructuredFile.out
 
 import com.fasterxml.jackson.databind.ObjectMapper
 import io.tolgee.dtos.IExportParams
+import io.tolgee.exceptions.ExportCollidingKeysException
 import io.tolgee.formats.ExportFormat
 import io.tolgee.formats.ExportMessageFormat
+import io.tolgee.formats.formKeywords
 import io.tolgee.formats.generic.IcuToGenericFormatMessageConvertor
 import io.tolgee.formats.nestedStructureModel.StructureModelBuilder
 import io.tolgee.formats.path.ObjectPathItem
@@ -39,11 +41,30 @@ class GenericStructuredFileExporter(
   }
 
   private fun prepare() {
+    if (pluralsViaSuffixes) {
+      checkPluralSuffixCollisions()
+    }
     translations.forEach { translation ->
       addTranslationToBuilder(translation)
     }
   }
 
+  private fun checkPluralSuffixCollisions() {
+    val allKeyNames = translations.map { it.key.name }.toSet()
+    translations.filter { it.key.isPlural }.forEach { translation ->
+      for (suffix in formKeywords) {
+        val suffixedName = "${translation.key.name}_$suffix"
+        if (suffixedName in allKeyNames) {
+          throw ExportCollidingKeysException(
+            pluralKey = translation.key.name,
+            collidingKey = suffixedName,
+            suffix = suffix,
+          )
+        }
+      }
+    }
+  }
+
   private fun addTranslationToBuilder(translation: ExportTranslationView) {
     if (translation.key.isPlural) {
       addPluralTranslation(translation)

backend/data/src/test/kotlin/io/tolgee/unit/formats/i18next/out/I18nextFileExporterTest.kt

@@ -2,6 +2,7 @@ package io.tolgee.unit.formats.i18next.out
 
 import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
 import io.tolgee.dtos.request.export.ExportParams
+import io.tolgee.exceptions.ExportCollidingKeysException
 import io.tolgee.formats.ExportFormat
 import io.tolgee.formats.genericStructuredFile.out.CustomPrettyPrinter
 import io.tolgee.formats.json.out.JsonFileExporter
@@ -11,6 +12,8 @@ import io.tolgee.service.export.dataProvider.ExportTranslationView
 import io.tolgee.unit.util.assertFile
 import io.tolgee.unit.util.getExported
 import io.tolgee.util.buildExportTranslationList
+import org.assertj.core.api.Assertions.assertThat
+import org.assertj.core.api.Assertions.assertThatThrownBy
 import org.junit.jupiter.api.Test
 
 class I18nextFileExporterTest {
@@ -89,6 +92,38 @@ class I18nextFileExporterTest {
     )
   }
 
+  @Test
+  fun `throws on plural suffix collision with existing key`() {
+    val built =
+      buildExportTranslationList {
+        add(
+          languageTag = "en",
+          keyName = "profile.my-goals.plan",
+          text = "{count, plural, other {Other}}",
+        ) {
+          key.isPlural = true
+        }
+        add(
+          languageTag = "en",
+          keyName = "profile.my-goals.plan_other",
+          text = "Some translation",
+        )
+      }
+    val exporter =
+      getExporter(
+        built.translations,
+        exportParams = ExportParams(format = ExportFormat.JSON_I18NEXT),
+      )
+    assertThatThrownBy { exporter.produceFiles() }
+      .isInstanceOf(ExportCollidingKeysException::class.java)
+      .satisfies({ ex ->
+        val bre = ex as ExportCollidingKeysException
+        assertThat(bre.pluralKey).isEqualTo("profile.my-goals.plan")
+        assertThat(bre.collidingKey).isEqualTo("profile.my-goals.plan_other")
+        assertThat(bre.suffix).isEqualTo("other")
+      })
+  }
+
   private fun getTranslationWithColon(): MutableList<ExportTranslationView> {
     val built =
       buildExportTranslationList {

webapp/src/i18n/en.json

@@ -739,6 +739,7 @@
   "cannot_change_your_own_access_tooltip": "Cannot revoke access to yourself",
   "cannot_delete_base_language_message": "Cannot delete base language",
   "cannot_delete_branch_with_children": "Cannot delete this branch because other branches were created from it.",
+  "export_key_plural_suffix_collision": "Export failed: plural key \"{pluralKey}\" with suffix \"_{suffix}\" collides with existing key \"{collidingKey}\". Rename one of the keys to resolve the conflict.",
   "cannot_leave_project_with_organization_role_error_message": "Cannot leave project owned by the organization you are member of.",
   "cannot_modify_disabled_translation": "Cannot modify disabled translation",
   "cannot_modify_reviewed_translation": "Cannot modify reviewed translation",

webapp/src/service/apiSchema.generated.ts

@@ -2896,7 +2896,8 @@ export interface components {
         | "branch_merge_revision_not_valid"
         | "branch_merge_conflicts_not_resolved"
         | "branch_merge_already_merged"
-        | "branching_not_enabled_for_project";
+        | "branching_not_enabled_for_project"
+        | "export_key_plural_suffix_collision";
       params?: unknown[];
     };
     ExistenceEntityDescription: {
@@ -6272,7 +6273,8 @@ export interface components {
         | "branch_merge_revision_not_valid"
         | "branch_merge_conflicts_not_resolved"
         | "branch_merge_already_merged"
-        | "branching_not_enabled_for_project";
+        | "branching_not_enabled_for_project"
+        | "export_key_plural_suffix_collision";
       params?: unknown[];
       success: boolean;
     };

webapp/src/translationTools/useErrorTranslation.ts

@@ -213,6 +213,12 @@ export function useErrorTranslation() {
         return t('operation_not_permitted_in_read_only_mode');
       case 'cannot_delete_branch_with_children':
         return t('cannot_delete_branch_with_children');
+      case 'export_key_plural_suffix_collision':
+        return t('export_key_plural_suffix_collision', {
+          pluralKey: params?.[0] || '',
+          collidingKey: params?.[1] || '',
+          suffix: params?.[2] || '',
+        });
       default:
         return code;
     }