Skip to content

Latest commit

 

History

History
161 lines (125 loc) · 4.77 KB

replaceTranslation.md

File metadata and controls

161 lines (125 loc) · 4.77 KB
Raw

replaceTranslation

Usage

To replace a translation into a xliff file:

//
use Matecat\XliffParser\XliffParser;

$parser = new XliffParser();
$parser->replaceTranslation($inputFile, $data, $transUnits, $targetLang, $outputFile, $callback);

Where:

  • $inputFile is the input file full path
  • $data is the data array
  • $transUnits is the trans-unit id reverse map
  • $targetLang is the target language
  • $outputFile is the output file full path (if the file does not exist il will be created)
  • $callback is an optional callback used to validate translations. It MUST implement XliffReplacerCallbackInterface and expose thereAreErrors method.

Examples

Here is a full example:

// ...

class DummyXliffReplacerCallback implements XliffReplacerCallbackInterface
{
    /**
     * @inheritDoc
     * 
     * @return bool
     */
    public function thereAreErrors( $segmentId, $segment, $translation, array $dataRefMap = [] )
    {
        return false;
    }
}

$data = [
    [
        'sid' => 1,
        'segment' => '<pc id="1">Hello <mrk id="m2" type="term">World</mrk> !</pc>',
        'internal_id' => 'u1',
        'mrk_id' => '',
        'prev_tags' => '',
        'succ_tags' => '',
        'mrk_prev_tags' => '',
        'mrk_succ_tags' => '',
        'translation' => '<pc id="1">Buongiorno al <mrk id="m2" type="term">Mondo</mrk> !</pc>',
        'status' => TranslationStatus::STATUS_TRANSLATED,
        'eq_word_count' => 123,
        'raw_word_count' => 456,
    ],
    [
        'sid' => 2,
        'segment' => '<pc id="1">Hello <mrk id="m2" type="term">World2</mrk> !</pc>',
        'internal_id' => 'u2',
        'mrk_id' => '',
        'prev_tags' => '',
        'succ_tags' => '',
        'mrk_prev_tags' => '',
        'mrk_succ_tags' => '',
        'translation' => '<pc id="2">Buongiorno al <mrk id="m2" type="term">Mondo2</mrk> !</pc>',
        'status' => TranslationStatus::STATUS_TRANSLATED,
        'eq_word_count' => 54353,
        'raw_word_count' => 54354,
    ],
];

$transUnits = [];

foreach ( $data as $i => $k ) {
    //create a secondary indexing mechanism on segments' array; this will be useful
    //prepend a string so non-trans unit id ( ex: numerical ) are not overwritten
    $internalId = $k[ 'internal_id' ];

    $transUnits[ $internalId ] [] = $i;

    $data[ 'matecat|' . $internalId ] [] = $i;
}

$inputFile = __DIR__.'/../tests/files/sample-20.xlf';
$outputFile = __DIR__.'/../tests/files/output/sample-20.xlf';

$parser = new XliffParser();
$parser->replaceTranslation( $inputFile, $data, $transUnits, 'fr-fr', $outputFile, new DummyXliffReplacerCallback() );

Missing target node in the original file

XliffParser is capable to create a target node if this is missing in the original xliff file.

Please note that the <target> will be placed:

  • just BEFORE its corresponding closing </trans-unit> for xliff 1.* files
  • just BEFORE its corresponding closing </segment> for xliff 2.* files

Take a look at this example taken from a xliff 2.0 file.

This is the original unit:

<unit id="tu1">
    <segment>
        <source xml:space="preserve">Titolo del documento</source>
    </segment>
</unit>

And this is the corresponding unit in the replaced file:

<unit help-id="1" id="tu1">
   <segment>
    <source xml:space="preserve">Titolo del documento</source>
   <target>Document title</target></segment>
            <mda:metadata>
                <mda:metagroup category="row_xml_attribute">
                    <mda:meta type="x-matecat-raw">0</mda:meta>
                    <mda:meta type="x-matecat-weighted">0</mda:meta>
                </mda:metagroup>
            </mda:metadata>
  </unit>

translate attribute

Translations will be not replaced in trans-units when translate attribute set to no.

Consider this trans-unit taken from a classic xliff v1.2 file:

<trans-unit help-id="1" id="1" restype="x-xhtml-madcap:keyword-term" phase-name="pretrans" translate="no">
	<source>Tools:Review</source>
	<seg-source>
		<mrk mtype="seg" mid="1">Tools:Review</mrk>
	</seg-source>
	<target state="needs-translation">
		<mrk mtype="seg" mid="1" MadCap:segmentStatus="Untranslated" MadCap:matchPercent="0"/>
	</target>
</trans-unit>

In this case the replacer will do not touch target and it is simply left as is.

Validation

Xliff 2.*

Every xliff 2.* file generated from the replacer will be compliant with the latest version of the OASIS specification.

Replacer will take care of:

  • adding missing namespaces (like xmlns:mda="urn:oasis:names:tc:xliff:metadata:2.0) if needed
  • copying attributes from <source> to <target> if needed
  • adding <mda:metadata> before <notes>/<originalData>/<segment>/<ignorable> tags