LocalChangeCommentsTest.php

Go to the documentation of this file.

<?php
 
declare(strict_types=1);
 
namespace ILIAS\Language\ComponentTranslation;
 
use ILIAS\Language\ComponentTranslation\Catalog\TranslationCatalog;
use ILIAS\Language\ComponentTranslation\Catalog\TranslationEntry;
use PHPUnit\Framework\Attributes\DataProvider;
use PHPUnit\Framework\TestCase;
 
class LocalChangeCommentsTest extends TestCase
{
    public function testANewlyMigratedEntryHasNoLocalChangeRightAfterOriginalIsSet(): void
    {
        $translation = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($translation, 'Hallo');
 
        $this->assertSame('Hallo', LocalChangeComments::getOriginal($translation));
        $this->assertNull(LocalChangeComments::getLocalChange($translation));
    }
 
    public function testRefreshSetsALocalChangeTimestampWhenTheValueDiffersFromTheOriginal(): void
    {
        $translation = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($translation, 'Hallo');
 
        $now = new \DateTimeImmutable('2026-09-21T10:00:00Z');
        LocalChangeComments::refresh($translation, 'Hallo', 'Hallo, geändert', $now);
 
        $this->assertSame('2026-09-21T10:00:00Z', LocalChangeComments::getLocalChange($translation));
    }
 
    public function testRefreshClearsTheLocalChangeWhenTheValueIsSetBackToTheOriginal(): void
    {
        $translation = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($translation, 'Hallo');
        LocalChangeComments::refresh(
            $translation,
            'Hallo',
            'Hallo, geändert',
            new \DateTimeImmutable('2026-09-21T10:00:00Z')
        );
 
        LocalChangeComments::refresh(
            $translation,
            'Hallo, geändert',
            'Hallo',
            new \DateTimeImmutable('2026-09-21T14:00:00Z')
        );
 
        $this->assertNull(LocalChangeComments::getLocalChange($translation));
        // "original" itself must never be touched by refresh()
        $this->assertSame('Hallo', LocalChangeComments::getOriginal($translation));
    }
 
    public function testRefreshDoesNotBumpAnAlreadyCurrentTimestampOnAnIdempotentResave(): void
    {
        $translation = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($translation, 'Hallo');
        LocalChangeComments::refresh(
            $translation,
            'Hallo',
            'Hallo, geändert',
            new \DateTimeImmutable('2026-09-21T10:00:00Z')
        );
 
        // same value written again, e.g. an unrelated key in the same module was edited too
        LocalChangeComments::refresh(
            $translation,
            'Hallo, geändert',
            'Hallo, geändert',
            new \DateTimeImmutable('2026-09-21T12:00:00Z')
        );
 
        $this->assertSame('2026-09-21T10:00:00Z', LocalChangeComments::getLocalChange($translation));
    }
 
    public function testRefreshUpdatesAnExistingTimestampWhenTheValueChangesAgain(): void
    {
        $translation = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($translation, 'Hallo');
        LocalChangeComments::refresh(
            $translation,
            'Hallo',
            'Hallo, geändert',
            new \DateTimeImmutable('2026-09-21T10:00:00Z')
        );
 
        LocalChangeComments::refresh(
            $translation,
            'Hallo, geändert',
            'Hallo, nochmal geändert',
            new \DateTimeImmutable('2026-09-21T12:00:00Z')
        );
 
        $this->assertSame('2026-09-21T12:00:00Z', LocalChangeComments::getLocalChange($translation));
    }
 
    public function testRefreshTreatsAMissingOriginalAsAlwaysLocallyChanged(): void
    {
        $translation = new TranslationEntry('demo', 'brand_new_key');
 
        LocalChangeComments::refresh($translation, '', 'Neuer Wert', new \DateTimeImmutable('2026-09-21T15:00:00Z'));
 
        $this->assertNull(LocalChangeComments::getOriginal($translation));
        $this->assertSame('2026-09-21T15:00:00Z', LocalChangeComments::getLocalChange($translation));
    }
 
    public function testRefreshNeverLeavesMoreThanOneLocalChangeCommentBehind(): void
    {
        $translation = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($translation, 'Hallo');
 
        LocalChangeComments::refresh($translation, 'Hallo', 'A', new \DateTimeImmutable('2026-09-21T10:00:00Z'));
        LocalChangeComments::refresh($translation, 'A', 'B', new \DateTimeImmutable('2026-09-21T11:00:00Z'));
        LocalChangeComments::refresh($translation, 'B', 'C', new \DateTimeImmutable('2026-09-21T12:00:00Z'));
 
        $localChangeComments = array_values(array_filter(
            $translation->getTranslatorComments(),
            static fn(string $comment): bool => str_starts_with($comment, 'local_change: ')
        ));
 
        $this->assertCount(1, $localChangeComments);
        $this->assertSame('local_change: 2026-09-21T12:00:00Z', $localChangeComments[0]);
    }
 
    #[DataProvider('valuesNeedingEscaping')]
    public function testAValueWithALineBreakOrBackslashRoundTripsExactlyViaASingleEscapedComment(
        string $value,
        string $expected_comment
    ): void {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, $value);
 
        $this->assertSame([$expected_comment], $entry->getTranslatorComments());
        $this->assertSame($value, LocalChangeComments::getOriginal($entry));
    }
 
    public static function valuesNeedingEscaping(): array
    {
        return [
            'LF' => ["Zeile eins\nZeile zwei", 'original_escaped: Zeile eins\\nZeile zwei'],
            'CRLF' => ["Zeile eins\r\nZeile zwei", 'original_escaped: Zeile eins\\r\\nZeile zwei'],
            'lone CR' => ["a\rb", 'original_escaped: a\\rb'],
            'trailing LF' => ["Hallo\n", 'original_escaped: Hallo\\n'],
            'backslash' => ['C:\\pfad', 'original_escaped: C:\\\\pfad'],
            // A literal backslash followed by "n" must not come back as a line feed
            'literal backslash-n' => ['a\\nb', 'original_escaped: a\\\\nb'],
            'literal backslash before a real LF' => ["a\\\nb", 'original_escaped: a\\\\\\nb'],
            'double backslash' => ['a\\\\b', 'original_escaped: a\\\\\\\\b'],
            'only a line break' => ["\n", 'original_escaped: \\n'],
        ];
    }
 
    public static function valuesSurvivingAPoFileRoundTrip(): array
    {
        return self::valuesNeedingEscaping() + [
            'leading and trailing spaces' => ['  Hallo  ', 'original:   Hallo  '],
            'trailing tab' => ["Hallo\t", "original: Hallo\t"],
            'only a space' => [' ', 'original:  '],
            'empty' => ['', 'original: '],
            'zero' => ['0', 'original: 0'],
            'escaped with surrounding spaces' => ["  a\nb  ", 'original_escaped:   a\\nb  '],
        ];
    }
 
    public function testAValueWithoutLineBreakOrBackslashIsStoredVerbatimUnderTheLegacyPrefix(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, 'Hallo "Welt" %s #:# ###');
 
        $this->assertSame(['original: Hallo "Welt" %s #:# ###'], $entry->getTranslatorComments());
    }
 
    #[DataProvider('legacyOriginalComments')]
    public function testALegacyOriginalCommentIsReadVerbatim(string $comment, string $expected): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $entry->addTranslatorComment($comment);
 
        $this->assertSame($expected, LocalChangeComments::getOriginal($entry));
    }
 
    public static function legacyOriginalComments(): array
    {
        return [
            'flattened line break' => ['original: a b', 'a b'],
            'unescaped backslash' => ['original: C:\\pfad', 'C:\\pfad'],
            'backslash-n stays two characters' => ['original: a\\nb', 'a\\nb'],
        ];
    }
 
    public function testALegacyCommentWithABackslashIsMigratedToTheEscapedPrefixWithoutALocalChange(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $entry->addTranslatorComment('original: C:\\pfad');
 
        LocalChangeComments::refresh($entry, 'C:\\pfad', 'C:\\pfad', new \DateTimeImmutable('2026-09-21T10:00:00Z'));
        $this->assertNull(LocalChangeComments::getLocalChange($entry));
 
        LocalChangeComments::setOriginal($entry, 'C:\\pfad');
        $this->assertSame(['original_escaped: C:\\\\pfad'], $entry->getTranslatorComments());
        $this->assertSame('C:\\pfad', LocalChangeComments::getOriginal($entry));
    }
 
    public function testSwitchingBetweenEscapedAndVerbatimValuesKeepsExactlyOneOriginalComment(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $entry->addTranslatorComment('translator note');
 
        LocalChangeComments::setOriginal($entry, "Zeile\nzwei");
        LocalChangeComments::setOriginal($entry, 'einzeilig');
        $this->assertSame(['translator note', 'original: einzeilig'], $entry->getTranslatorComments());
        $this->assertSame('einzeilig', LocalChangeComments::getOriginal($entry));
 
        LocalChangeComments::setOriginal($entry, "wieder\nmehrzeilig");
        $this->assertSame(['translator note', 'original_escaped: wieder\\nmehrzeilig'], $entry->getTranslatorComments());
        $this->assertSame("wieder\nmehrzeilig", LocalChangeComments::getOriginal($entry));
    }
 
    public function testSetOriginalWithTheSameEscapedValueKeepsTheCommentOrderStable(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, "Zeile\r\nzwei");
        $entry->addTranslatorComment('translator note');
 
        LocalChangeComments::setOriginal($entry, "Zeile\r\nzwei");
 
        $this->assertSame(['original_escaped: Zeile\\r\\nzwei', 'translator note'], $entry->getTranslatorComments());
    }
 
    public function testSetOriginalRemovesAStaleCommentOfTheOtherPrefix(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $entry->addTranslatorComment('original: Hallo');
        $entry->addTranslatorComment('original_escaped: Alt\\nZeile');
 
        LocalChangeComments::setOriginal($entry, 'Hallo');
 
        $this->assertSame(['original: Hallo'], $entry->getTranslatorComments());
        $this->assertSame('Hallo', LocalChangeComments::getOriginal($entry));
    }
 
    public function testRefreshComparesAMultiLineValueAgainstTheDecodedOriginal(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, "Zeile eins\r\nZeile zwei");
 
        LocalChangeComments::refresh($entry, "Zeile eins\r\nZeile zwei", "Zeile eins\r\nZeile zwei", new \DateTimeImmutable('2026-09-21T10:00:00Z'));
        $this->assertNull(LocalChangeComments::getLocalChange($entry));
 
        LocalChangeComments::refresh($entry, "Zeile eins\r\nZeile zwei", "Zeile eins\nZeile zwei", new \DateTimeImmutable('2026-09-21T11:00:00Z'));
        $this->assertSame('2026-09-21T11:00:00Z', LocalChangeComments::getLocalChange($entry));
    }
 
    #[DataProvider('valuesSurvivingAPoFileRoundTrip')]
    public function testTheOriginalSurvivesAPoFileRoundTrip(string $value, string $expected_comment): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $entry->translate($value);
        LocalChangeComments::setOriginal($entry, $value);
        $entry->addTranslatorComment('local_change: 2026-09-21T10:00:00Z');
        $catalog = new TranslationCatalog();
        $catalog->add($entry);
 
        $parsed = TranslationCatalog::fromPoString($catalog->toPoString())->find('demo', 'greeting');
 
        $this->assertNotNull($parsed);
        $this->assertSame([$expected_comment, 'local_change: 2026-09-21T10:00:00Z'], $parsed->getTranslatorComments());
        $this->assertSame($value, LocalChangeComments::getOriginal($parsed));
        $this->assertSame($value, $parsed->getTranslation());
    }
 
    public function testSetOriginalWithTheSameValueKeepsTheCommentOrderStable(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, 'Hallo');
        $entry->addTranslatorComment('translator note');
 
        LocalChangeComments::setOriginal($entry, 'Hallo');
 
        $this->assertSame(['original: Hallo', 'translator note'], $entry->getTranslatorComments());
    }
 
    public function testSetOriginalWithADifferentValueReplacesTheOldOriginalInsteadOfAddingASecondOne(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, 'Hallo');
        $entry->addTranslatorComment('translator note');
 
        LocalChangeComments::setOriginal($entry, 'Servus');
 
        $this->assertSame(['translator note', 'original: Servus'], $entry->getTranslatorComments());
        $this->assertSame('Servus', LocalChangeComments::getOriginal($entry));
    }
 
    public function testOriginalKeepsLeadingAndTrailingWhitespaceExactly(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, '  Hallo ');
 
        $this->assertSame('  Hallo ', LocalChangeComments::getOriginal($entry));
 
        LocalChangeComments::refresh($entry, '  Hallo ', '  Hallo ', new \DateTimeImmutable('2026-09-21T10:00:00Z'));
        $this->assertNull(LocalChangeComments::getLocalChange($entry));
    }
 
    public function testAnEmptyOriginalIsDistinctFromNoOriginal(): void
    {
        $entry = new TranslationEntry('demo', 'untranslated');
        LocalChangeComments::setOriginal($entry, '');
 
        $this->assertSame('', LocalChangeComments::getOriginal($entry));
        LocalChangeComments::refresh($entry, '', '', new \DateTimeImmutable('2026-09-21T10:00:00Z'));
        $this->assertNull(LocalChangeComments::getLocalChange($entry));
    }
 
    public function testRemoveOriginalRemovesBothTheLegacyAndTheEscapedPrefix(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $entry->addTranslatorComment('original: Hallo');
        $entry->addTranslatorComment('translator note');
        $entry->addTranslatorComment('original_escaped: Zeile\\nzwei');
 
        LocalChangeComments::removeOriginal($entry);
 
        $this->assertNull(LocalChangeComments::getOriginal($entry));
        $this->assertSame(['translator note'], $entry->getTranslatorComments());
    }
 
    public function testRemoveOriginalLeavesOtherCommentsAlone(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $entry->addTranslatorComment('translator note');
        LocalChangeComments::setOriginal($entry, 'Hallo');
        LocalChangeComments::refresh($entry, 'Hallo', 'Hi', new \DateTimeImmutable('2026-09-21T10:00:00Z'));
 
        LocalChangeComments::removeOriginal($entry);
 
        $this->assertNull(LocalChangeComments::getOriginal($entry));
        $this->assertSame(
            ['translator note', 'local_change: 2026-09-21T10:00:00Z'],
            $entry->getTranslatorComments()
        );
    }
 
    public function testGetLocalChangeAsDatabaseTimestampConvertsTheIsoFormat(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::refresh($entry, '', 'Hi', new \DateTimeImmutable('2026-12-31T23:59:59Z'));
 
        $this->assertSame('2026-12-31 23:59:59', LocalChangeComments::getLocalChangeAsDatabaseTimestamp($entry));
    }
 
    public function testGetLocalChangeAsDatabaseTimestampIsNullWithoutALocalChange(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, 'Hallo');
 
        $this->assertNull(LocalChangeComments::getLocalChangeAsDatabaseTimestamp($entry));
    }
 
    public function testGetLocalChangeAsDatabaseTimestampIsNullForAnUnparsableTimestamp(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $entry->addTranslatorComment('local_change: yesterday');
 
        $this->assertSame('yesterday', LocalChangeComments::getLocalChange($entry));
        $this->assertNull(LocalChangeComments::getLocalChangeAsDatabaseTimestamp($entry));
    }
 
    public function testGetRemarkIsNullWithoutOneSet(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
 
        $this->assertNull(LocalChangeComments::getRemark($entry));
    }
 
    public function testSetRemarkAndGetRemarkRoundTripAPlainValueVerbatim(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setRemark($entry, 'Bitte prüfen');
 
        $this->assertSame(['remark: Bitte prüfen'], $entry->getTranslatorComments());
        $this->assertSame('Bitte prüfen', LocalChangeComments::getRemark($entry));
    }
 
    #[DataProvider('valuesNeedingEscaping')]
    public function testSetRemarkEscapesALineBreakOrBackslashLikeSetOriginalDoes(string $value, string $unused_original_comment): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setRemark($entry, $value);
 
        $comments = $entry->getTranslatorComments();
        $this->assertCount(1, $comments);
        $this->assertStringStartsWith('remark_escaped: ', $comments[0]);
        $this->assertSame($value, LocalChangeComments::getRemark($entry));
    }
 
    public function testSetRemarkKeepsLeadingAndTrailingWhitespaceExactly(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setRemark($entry, '  Bemerkung  ');
 
        $this->assertSame('  Bemerkung  ', LocalChangeComments::getRemark($entry));
    }
 
    public function testSetRemarkWithAnEmptyStringRemovesIt(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setRemark($entry, 'Bitte prüfen');
 
        LocalChangeComments::setRemark($entry, '');
 
        $this->assertNull(LocalChangeComments::getRemark($entry));
        $this->assertSame([], $entry->getTranslatorComments());
    }
 
    public function testSetRemarkWithNullRemovesAnExistingOne(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setRemark($entry, 'Bitte prüfen');
 
        LocalChangeComments::setRemark($entry, null);
 
        $this->assertNull(LocalChangeComments::getRemark($entry));
    }
 
    public function testSetRemarkThrowsForInvalidUtf8(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
 
        $this->expectException(\InvalidArgumentException::class);
        LocalChangeComments::setRemark($entry, "Ung\xFCltig");
    }
 
    public function testSetRemarkIsCutToMaxRemarkLengthCharactersNotBytes(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        // 250 "ä" (2 bytes each in UTF-8) plus one more character right at the boundary
        $remark = str_repeat('ä', LocalChangeComments::MAX_REMARK_LENGTH) . 'X';
 
        LocalChangeComments::setRemark($entry, $remark);
 
        $stored = LocalChangeComments::getRemark($entry);
        $this->assertSame(LocalChangeComments::MAX_REMARK_LENGTH, mb_strlen((string) $stored));
        $this->assertSame(str_repeat('ä', LocalChangeComments::MAX_REMARK_LENGTH), $stored);
        $this->assertTrue(mb_check_encoding((string) $stored, 'UTF-8'), 'no character was split in half');
    }
 
    public function testSetRemarkAtExactlyMaxRemarkLengthIsNotCut(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        $remark = str_repeat('x', LocalChangeComments::MAX_REMARK_LENGTH);
 
        LocalChangeComments::setRemark($entry, $remark);
 
        $this->assertSame($remark, LocalChangeComments::getRemark($entry));
    }
 
    public function testSetRemarkSwitchingBetweenEscapedAndPlainKeepsExactlyOneComment(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setRemark($entry, "mit\nZeilenumbruch");
 
        LocalChangeComments::setRemark($entry, 'ohne Umbruch');
 
        $this->assertSame(['remark: ohne Umbruch'], $entry->getTranslatorComments());
        $this->assertSame('ohne Umbruch', LocalChangeComments::getRemark($entry));
    }
 
    public function testRemarkCoexistsWithOriginalAndLocalChangeOnTheSameEntry(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, 'Hallo');
        LocalChangeComments::refresh($entry, 'Hallo', 'Servus', new \DateTimeImmutable('2026-09-21T10:00:00Z'));
 
        LocalChangeComments::setRemark($entry, 'Bitte prüfen');
 
        $this->assertSame('Hallo', LocalChangeComments::getOriginal($entry));
        $this->assertSame('2026-09-21T10:00:00Z', LocalChangeComments::getLocalChange($entry));
        $this->assertSame('Bitte prüfen', LocalChangeComments::getRemark($entry));
 
        LocalChangeComments::setRemark($entry, null);
 
        $this->assertNull(LocalChangeComments::getRemark($entry));
        $this->assertSame('Hallo', LocalChangeComments::getOriginal($entry), 'removing the remark must not touch "original"');
        $this->assertSame('2026-09-21T10:00:00Z', LocalChangeComments::getLocalChange($entry), 'nor "local_change"');
    }
 
    public function testRemarkCoexistsWithPerFormOriginalsOfAPluralMessage(): void
    {
        $entry = new TranslationEntry('demo', 'greeting');
        LocalChangeComments::setOriginal($entry, 'Eintrag', 0);
        LocalChangeComments::setOriginal($entry, 'Einträge', 1);
 
        LocalChangeComments::setRemark($entry, 'Bitte prüfen');
 
        $this->assertSame('Eintrag', LocalChangeComments::getOriginal($entry, 0));
        $this->assertSame('Einträge', LocalChangeComments::getOriginal($entry, 1));
        $this->assertSame('Bitte prüfen', LocalChangeComments::getRemark($entry));
 
        LocalChangeComments::removeFormOriginals($entry);
 
        $this->assertSame('Bitte prüfen', LocalChangeComments::getRemark($entry), 'removing the form originals must not touch the remark');
    }
}