fix: detect i18next plural suffix collision on export (Sentry TOLGEE-BACKEND-3ED)

When exporting to i18next format, plural keys get suffixed (e.g.,
"plan" → "plan_other"). If a non-plural key with the same suffixed
name already exists, the export crashed with an IllegalStateException.

Now detect such collisions upfront and throw a BadRequestException
with a clear message identifying both the plural key and the
colliding key, so the user can resolve the naming conflict.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bdshadow

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

@@ -324,6 +324,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

@@ -738,6 +738,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

@@ -2893,7 +2893,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: {
@@ -6268,7 +6269,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;
     }