feat: support gettext msgctxt in PO import/export and UI

backend/data/src/main/kotlin/io/tolgee/development/testDataBuilder/data/PoMsgctxtTestData.kt

@@ -0,0 +1,19 @@
+package io.tolgee.development.testDataBuilder.data
+
+class PoMsgctxtTestData : BaseTestData() {
+  init {
+    projectBuilder.apply {
+      addKey {
+        name = "plain.key"
+      }.build {
+        addTranslation("en", "Plain key without msgctxt")
+      }
+
+      addKey {
+        name = "menu\u0004Open"
+      }.build {
+        addTranslation("en", "Open file from the menu")
+      }
+    }
+  }
+}

backend/data/src/main/kotlin/io/tolgee/formats/po/contsants.kt

@@ -1,3 +1,5 @@
 package io.tolgee.formats.po
 
 const val PO_FILE_MSG_ID_PLURAL_CUSTOM_KEY = "_poFileMsgIdPlural"
+
+const val PO_MSGCTXT_KEY_SEPARATOR = "\u0004"

backend/data/src/main/kotlin/io/tolgee/formats/po/in/PoFileProcessor.kt

@@ -6,6 +6,7 @@ import io.tolgee.formats.ImportFileProcessor
 import io.tolgee.formats.MessageConvertorResult
 import io.tolgee.formats.importCommon.ImportFormat
 import io.tolgee.formats.po.PO_FILE_MSG_ID_PLURAL_CUSTOM_KEY
+import io.tolgee.formats.po.PO_MSGCTXT_KEY_SEPARATOR
 import io.tolgee.formats.po.`in`.data.PoParsedTranslation
 import io.tolgee.formats.po.`in`.data.PoParserResult
 import io.tolgee.model.dataImport.ImportLanguage
@@ -26,7 +27,7 @@ class PoFileProcessor(
       context.languages[languageId] = ImportLanguage(languageId, context.fileEntity)
 
       parsed.translations.forEachIndexed { idx, poTranslation ->
-        val keyName = poTranslation.msgid.toString()
+        val keyName = buildKeyName(poTranslation)
 
         if (poTranslation.msgidPlural.isNotEmpty()) {
           addPlural(poTranslation, idx)
@@ -72,7 +73,7 @@ class PoFileProcessor(
     val plurals = poTranslation.msgstrPlurals?.map { it.key to it.value.toString() }?.toMap()
     plurals?.let {
       val (converted, convertedBy) = getConvertedMessage(poTranslation, plurals)
-      val keyName = poTranslation.msgid.toString()
+      val keyName = buildKeyName(poTranslation)
       poTranslation.msgidPlural.toString().nullIfEmpty?.let {
         context.setCustom(keyName, PO_FILE_MSG_ID_PLURAL_CUSTOM_KEY, it)
       }
@@ -88,6 +89,15 @@ class PoFileProcessor(
     }
   }
 
+  private fun buildKeyName(poTranslation: PoParsedTranslation): String {
+    val msgid = poTranslation.msgid.toString()
+    val msgctxt = poTranslation.msgctxt.toString()
+    if (msgctxt.isEmpty()) {
+      return msgid
+    }
+    return "$msgctxt$PO_MSGCTXT_KEY_SEPARATOR$msgid"
+  }
+
   private fun getConvertedMessage(
     poTranslation: PoParsedTranslation,
     stringOrPluralForms: Any?,

backend/data/src/main/kotlin/io/tolgee/formats/po/in/PoParser.kt

@@ -4,14 +4,13 @@ import io.tolgee.exceptions.PoParserException
 import io.tolgee.formats.po.`in`.data.PoParsedTranslation
 import io.tolgee.formats.po.`in`.data.PoParserMeta
 import io.tolgee.formats.po.`in`.data.PoParserResult
-import io.tolgee.model.dataImport.issues.issueTypes.FileIssueType
-import io.tolgee.model.dataImport.issues.paramTypes.FileIssueParamType
 import io.tolgee.service.dataImport.processors.FileProcessorContext
 import java.util.Locale
 
 class PoParser(
   private val context: FileProcessorContext,
 ) {
+  private var expectMsgCtxt = false
   private var expectMsgId = false
   private var expectMsgStr = false
   private var expectMsgIdPlural = false
@@ -50,7 +49,7 @@ class PoParser(
 
   private fun processHeader(): PoParserMeta {
     val result = PoParserMeta()
-    translations.filter { it.msgid.toString() == "" }.forEach {
+    translations.filter { it.msgid.toString() == "" && it.msgctxt.toString() == "" }.forEach {
       it.msgstr.split("\n").map { metaLine ->
         val trimmed = metaLine.trim()
         if (trimmed.isBlank()) {
@@ -253,10 +252,8 @@ class PoParser(
       }
 
       isKeyword("msgctxt") -> {
-        context.fileEntity.addIssue(
-          FileIssueType.PO_MSGCTXT_NOT_SUPPORTED,
-          mapOf(FileIssueParamType.LINE to currentLine.toString()),
-        )
+        possibleEndTranslationBefore()
+        expectMsgCtxt = true
       }
 
       current.matches("^msgstr\\[\\d+]$".toRegex()) -> {
@@ -294,6 +291,10 @@ class PoParser(
 
   private fun storeCurrent() {
     createdTranslation.apply {
+      if (expectMsgCtxt) {
+        this.msgctxt.append(currentSequence)
+      }
+
       if (expectMsgId) {
         this.msgid.append(currentSequence)
       }
@@ -322,6 +323,7 @@ class PoParser(
 
   private fun resetValueExpectations() {
     expectValue = false
+    expectMsgCtxt = false
     expectMsgId = false
     expectMsgStr = false
     expectMsgIdPlural = false

backend/data/src/main/kotlin/io/tolgee/formats/po/in/data/PoParsedTranslation.kt

@@ -1,6 +1,7 @@
 package io.tolgee.formats.po.`in`.data
 
 class PoParsedTranslation {
+  var msgctxt: StringBuilder = StringBuilder()
   var msgid: StringBuilder = StringBuilder()
   var msgidPlural: StringBuilder = StringBuilder()
   var msgstr: StringBuilder = StringBuilder()

backend/data/src/main/kotlin/io/tolgee/formats/po/out/PoFileExporter.kt

@@ -4,11 +4,13 @@ import io.tolgee.dtos.IExportParams
 import io.tolgee.formats.ExportMessageFormat
 import io.tolgee.formats.getPluralData
 import io.tolgee.formats.po.PO_FILE_MSG_ID_PLURAL_CUSTOM_KEY
+import io.tolgee.formats.po.PO_MSGCTXT_KEY_SEPARATOR
 import io.tolgee.model.ILanguage
 import io.tolgee.service.export.ExportFilePathProvider
 import io.tolgee.service.export.dataProvider.ExportTranslationView
 import io.tolgee.service.export.exporters.FileExporter
 import java.io.InputStream
+import kotlin.text.split
 
 class PoFileExporter(
   val translations: List<ExportTranslationView>,
@@ -33,7 +35,8 @@ class PoFileExporter(
       val resultBuilder = getResultStringBuilder(translation)
       val converted = convertMessage(translation)
       resultBuilder.appendLine()
-      resultBuilder.writeMsgId(translation.key.name)
+      resultBuilder.writeMsgCtxt(translation.key.name.getMsgCtxt())
+      resultBuilder.writeMsgId(translation.key.name.getMsgId())
       resultBuilder.writeMsgIdPlural(translation, converted)
       resultBuilder.writeMsgStr(converted)
     }
@@ -49,6 +52,12 @@ class PoFileExporter(
     ).convert()
   }
 
+  private fun StringBuilder.writeMsgCtxt(msgctxt: String?) {
+    if (!msgctxt.isNullOrEmpty()) {
+      this.append(convertToPoMultilineString("msgctxt", msgctxt))
+    }
+  }
+
   private fun StringBuilder.writeMsgId(keyName: String) {
     this.append(convertToPoMultilineString("msgid", keyName))
   }
@@ -101,7 +110,8 @@ class PoFileExporter(
     translation: ExportTranslationView,
     converted: ToPoConversionResult,
   ) {
-    val msgIdPlural = translation.key.custom?.get(PO_FILE_MSG_ID_PLURAL_CUSTOM_KEY) as? String ?: translation.key.name
+    val msgIdPlural =
+      translation.key.custom?.get(PO_FILE_MSG_ID_PLURAL_CUSTOM_KEY) as? String ?: translation.key.name.getMsgId()
     if (converted.isPlural()) {
       this.append(
         convertToPoMultilineString(
@@ -111,4 +121,14 @@ class PoFileExporter(
       )
     }
   }
+
+  private fun String.getMsgId(): String {
+    val parts = split(PO_MSGCTXT_KEY_SEPARATOR, limit = 2)
+    return parts.last()
+  }
+
+  private fun String.getMsgCtxt(): String? {
+    val parts = split(PO_MSGCTXT_KEY_SEPARATOR, limit = 2)
+    return parts.takeIf { parts.size > 1 }?.first()
+  }
 }

backend/data/src/test/kotlin/io/tolgee/unit/formats/po/in/PoFileProcessorTest.kt

@@ -179,6 +179,44 @@ class PoFileProcessorTest {
       }
   }
 
+  @Test
+  fun `joins msgctxt and msgid into keyName via separator`() {
+    mockImportFile("example_msgctxt.po")
+    PoFileProcessor(mockUtil.fileProcessorContext).process()
+    val keys = mockUtil.fileProcessorContext.translations.keys
+    assertThat(keys).contains(
+      "menu\u0004Open",
+      "verb\u0004Open",
+      "Open",
+      "items\u0004%d item",
+    )
+  }
+
+  @Test
+  fun `drops msgctxt-only entry whose msgid is empty`() {
+    mockImportFile("example_msgctxt_only.po")
+    PoFileProcessor(mockUtil.fileProcessorContext).process()
+    assertThat(mockUtil.fileProcessorContext.translations.keys)
+      .containsExactly("menu\u0004Open")
+  }
+
+  @Test
+  fun `treats empty msgctxt as no msgctxt`() {
+    mockImportFile("example_msgctxt.po")
+    PoFileProcessor(mockUtil.fileProcessorContext).process()
+    val keys = mockUtil.fileProcessorContext.translations.keys
+    assertThat(keys).contains("Cancel")
+    assertThat(keys).doesNotContain("\u0004Cancel")
+  }
+
+  @Test
+  fun `preserves msgctxt escapes in keyName`() {
+    mockImportFile("example_msgctxt_escapes.po")
+    PoFileProcessor(mockUtil.fileProcessorContext).process()
+    val expected = "a \"quoted\" ctx\nwith newline\u0004Save"
+    assertThat(mockUtil.fileProcessorContext.translations.keys).contains(expected)
+  }
+
   @Test
   fun `respects provided format`() {
     mockUtil.mockIt("en.json", "src/test/resources/import/po/example.po")

backend/data/src/test/kotlin/io/tolgee/unit/formats/po/in/PoParserTest.kt

@@ -1,6 +1,7 @@
 package io.tolgee.unit.formats.po.`in`
 
 import io.tolgee.formats.po.`in`.PoParser
+import io.tolgee.model.dataImport.issues.issueTypes.FileIssueType
 import io.tolgee.util.FileProcessorContextMockUtil
 import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.BeforeEach
@@ -12,11 +13,11 @@ class PoParserTest {
   @BeforeEach
   fun setup() {
     mockUtil = FileProcessorContextMockUtil()
-    mockUtil.mockIt("example.po", "src/test/resources/import/po/example.po")
   }
 
   @Test
   fun `returns correct parsed result`() {
+    mockUtil.mockIt("example.po", "src/test/resources/import/po/example.po")
     val result = PoParser(mockUtil.fileProcessorContext)()
     assertThat(result.translations).hasSizeGreaterThan(8)
     assertThat(result.translations[5].msgstrPlurals).hasSize(2)
@@ -30,4 +31,47 @@ class PoParserTest {
     assertThat(result.translations[10].msgstr.toString()).isEqualTo("This\nis\na\nmultiline\nstring")
     assertThat(result.translations[11].msgstr.toString()).isEqualTo("This\r\nis\r\na\r\nmultiline\r\nstring")
   }
+
+  @Test
+  fun `parses msgctxt for each entry`() {
+    mockUtil.mockIt("example_msgctxt.po", "src/test/resources/import/po/example_msgctxt.po")
+    val result = PoParser(mockUtil.fileProcessorContext)()
+    val byMsgid =
+      result.translations
+        .filter { it.msgid.toString().isNotEmpty() }
+        .associateBy { it.msgctxt.toString() to it.msgid.toString() }
+
+    assertThat(byMsgid).containsKey("menu" to "Open")
+    assertThat(byMsgid).containsKey("verb" to "Open")
+    assertThat(byMsgid).containsKey("" to "Open")
+    assertThat(byMsgid["items" to "%d item"]?.msgidPlural?.toString()).isEqualTo("%d items")
+  }
+
+  @Test
+  fun `parses msgctxt containing escaped quotes and newlines`() {
+    mockUtil.mockIt("example_msgctxt_escapes.po", "src/test/resources/import/po/example_msgctxt_escapes.po")
+    val result = PoParser(mockUtil.fileProcessorContext)()
+    val entry = result.translations.first { it.msgid.toString() == "Save" }
+    assertThat(entry.msgctxt.toString()).isEqualTo("a \"quoted\" ctx\nwith newline")
+  }
+
+  @Test
+  fun `does not emit PO_MSGCTXT_NOT_SUPPORTED issue`() {
+    mockUtil.mockIt("example_msgctxt.po", "src/test/resources/import/po/example_msgctxt.po")
+    PoParser(mockUtil.fileProcessorContext)()
+    val emittedTypes =
+      mockUtil.fileProcessorContext.fileEntity.issues
+        .map { it.type }
+    assertThat(emittedTypes).doesNotContain(FileIssueType.PO_MSGCTXT_NOT_SUPPORTED)
+  }
+
+  @Test
+  fun `does not promote msgctxt-only entry with empty msgid to header`() {
+    mockUtil.mockIt("example_msgctxt_only.po", "src/test/resources/import/po/example_msgctxt_only.po")
+    val result = PoParser(mockUtil.fileProcessorContext)()
+    // The msgctxt-only-with-empty-msgid entry must not contribute header metadata
+    // (would otherwise be parsed as Key: value lines from its msgstr).
+    assertThat(result.meta.language).isEqualTo("de")
+    assertThat(result.meta.other).doesNotContainKey("garbage")
+  }
 }