Use cases

(For information on how length restrictions are configured, please scroll down)

Pixel-count based and character-count based length restrictions per segment and max line counts per segment currently can be defined for any file format, that translate5 can import.

Yet if used in such a generalistic way, the defined length for each segment of one task has to be the same and has to be defined in the task template (see below).

If you need different counts per segment within the same task, you need to define them directly in the xliff file before importing it into translate5 (see below).

Pixcel-count based length restriction

Pixel-count based length restrictions for a segment or a line within a segment are useful for the translation of display texts, where a certain display text must not exceed a certain number of pixel. For example the letter "i" might only need 3px width, while the letter "M" might need 12px width. translate5 can count the used pixel, if it is fed with enough information (see below).

Character-count based length restriction

In some cases instead of counting pixel-length it is important to count the number of used characters in a segment or a line. translate5 supports this also.

Support of min-width and max-width

With translate5 you can set a min-width and/or a max-width for a segment.

Support for line-count and line-length

A display text can have multiple lines. translate5 supports to check, that a max number of lines is not exceeded and a max number of pixel or characters per line is not exceeded. Minimum count of characters or pixel is only supported so far, if no max line  count is defined.

Usage and configuration

Usage overview

In short words

1. Optionally do definitions in xliff 1.2
2. Define
   
   1. task-template.xml
   2. pixel-mapping.xlsx (only if pixel-length check)
3. Use ZIP import package and include task-template.xml and optionally pixel-mapping.xlsx

More in detail

For length restrictions to be used in any case a task-template (task-template.xml) has to be provided for a task and length restrictions have to be activated there for the task (details see below).

For pixel-based length restrictions to work some default settings also have to be provided in the Zf_configuration database table (system configuration; see below). Also the pixel-width definitions have to be provided as an Excel file (pixel-mapping.xml ) that is fed alongside the task-template to the import zip for the task.

All length restrictions can also be provided directly in xliff 1.2 format on trans-unit level. If they are present, they overwrite definitions made in the task template (different font-sizes and fonts for pixel-based length check for different segments of the same task can currently only be used with custom file filters written by translate5s developers. It would also be possible to implement the definition of differently used fonts and font-sizes on segment-level within an xliff file. Currently only one font-size and one font per task is possible without custom import file filters).

To use other custom formats that already contain all length restriction definitions on segment level please ask the translate5 development team to develop a custom import file filter.

Definable parameters

You can define for the length check the following parameters in the task-template and may overwrite them in xliff 1.2

• size-unit
  • If the length check should be character-length based or pixel-length based
  • Possible values:
    • pixel
    • char
• minLength
  • Minimum length in number of pixel / characters
  • Refers to the length of a complete trans-unit of an xliff file, even if it spans multiple segments.
  • This means for min-length set in a task template for let's say a word document, that the length restriction refers to a whole paragraph.
  • If maxNumberOfLines is set, minLength is not supported so far (ask translate5's development team, if you need it)
• maxLength
  • Maximum length in number of pixel / characters
  • Refers to the length of a complete trans-unit of an xliff file, even if it spans multiple segments.
  • This means for maxLength set in a task template for let's say a word document, that the length restriction refers to a whole paragraph.
  • If maxNumberOfLines is set, maxLength refers to the length of each line, otherwise maxLength refers to the trans-unit
• translate5:maxNumberOfLines
  • How many lines a segment (not a trans-unit) should maximally have
  • If maxNumberOfLines is set,
    • maxLength refers to the length of each line, otherwise maxLength refers to the trans-unit
    • minLength is not supported so far (ask translate5's development team, if you need it)
• For pixel-based length check:
  • For each character for a certain font and a certain font-size the assumed pixel-width
    
    • Definitions in pixel-mapping.xlsx
  • What font-size and what font should be assumed for the current task

Task template definitions

For length restrictions to be activated, in any case a task template has to be used. The <lengthRestriction></lengthRestriction> tag has to be present in the task template and the task template has to be provided to the imported zip package.

Please see Task Templates for how to use that and ZIP import package format for how to include the task-template.xml into the import zip package.

Special settings for pixel length restriction

For this check to work somewhere the pixel length of each character of a used font in the used font-size has to be defined.

For this definitions in translate5s system configuration and in the pixel-mapping.xlsx file have to be made (see below).

System configuration in Zf_configuration for pixel length restriction

For every font-size that might be used, default pixel width have to be defined in the Zf_configuration table in case of characters that are missing in the pixel-mapping.xlsx file.

pixel-mapping.xlsx: Pixel-length definitions by character

The pixel-mapping.xlsx file has to be provided within the ZIP import package (please go here for more information on the zip package format).

Please find an example for pixel-mapping.xlsx below.

Explanation of columns in pixel-mapping.xlsx

• font: Contains the font-name as used in the task-template
• fontSize: Contains the font-size as used in the task-template
• unicodeChar: Contains the value unicode code point value for the character, for which you want to define a pixel width. An easy way to find the code point is to use the site https://onlineutf8tools.com/convert-utf8-to-code-points and to enter the char you want to know the code point of in the left field.
• pixelWidth: The pixel width you want to define for the listed character, with the listed font in the listed font-size
• Character: This is just a reference column to be easily able to know, what the current row defines. It is not used during the length check.

Example pixel-mapping.xlsx file

Definitions in xliff 1.2

(overwrite corresponding definitons in task template)

Example:

    <trans-unit id="4" translate5:maxNumberOfLines="2" minwidth="100" maxwidth="300" size-unit="pixel">
    <source>Example for maximal 2 lines, minwidth 100, maxWidth 300.</source>
    <target></target>
    </trans-unit>

Please note:

• translate5 uses translate5:maxNumberOfLines , not the maxheight-Element! (http://docs.oasis-open.org/xliff/v1.2/os/xliff-core.html#maxheight).
  The reason is, that with "pixel" as size-unit, the value of maxheight would refer to the pixel-height of the trans-unit, not to the number of lines.