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 generalist way, the defined length for each segment has to be the same for the complete task and has to be defined in the configuration.

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. Ask translate5s development team, if you need conversion of other file formats to xliff that support segment-based length restriction definitions.

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 minWidth and maxWidth

With translate5 you can set a minWidth and/or a maxWidth 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.

To support users editing segments for which a max. line count is defined, linebreaks will be inserted automatically at sensful positions when a user opens a segment being to long for editing. These "linebreak suggestions" must be accepted by the user by simply saving the segment.

Usage and configuration

Usage overview

In short words

1. Define relevant system configuration settings
2. Define
   1. pixel-mapping.xlsx (only if pixel-length check)
   2. Optionally define relevant parameters directly in xliff 1.2
3. Use ZIP import package and include pixel-mapping.xlsx if needed

Example import package

More in detail

For length restrictions to be used in any case system configuration has to be set.

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 ) 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 configuration.

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.

Regarding pixel-based length check:
Different font-sizes and fonts  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.

Definable parameters

Length check parameters definable in the configuration(see the table bellow) and overwriteable in xliff 1.2

• size-unit
  • If character-length or pixel-length based length check
  • Possible values:
    • pixel
    • char
• minWidth
  • 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 minWidth set in a system configuration for let's say a word document, that the length restriction refers to a whole paragraph.
  • If maxNumberOfLines is set, minWidth

Max. and min. length restrictions (so far only supported for XLIFF 1.2 import files; also works across all segments of a trans-unit). Length restriction can be

• character based (number of characters)
• pixel based (number of pixel for a defined font and font size; used for translation of display texts)

Settings for a task can be done in the task-template.xml and pixel-mapping.xml (which must be included in the task's import-ZIP). Details see below.

Default settings must be provided in the config. Details see below.

Settings for Length Restrictions

General settings are  set in the task-template. These can be overwritten by each trans-unit.

• If maxNumberOfLines is set, maxLength
  • refers to the length of each line, otherwise
  maxLength
  • minWidth refers to the trans-unit
  (which might span multiple segments).maxNumberOfLines
  • .
    
    • With maxNumberOfLines set, trans-units must not span multiple segments!
• maxWidth
  • 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 maxWidth set in a system configuration for let's say a word document, that the length restriction refers to a whole paragraph.
  • If maxNumberOfLines is set, maxWidth refers to the length of each line, otherwise maxWidth refers to the trans-unit.
    
    • With maxNumberOfLines set, trans-units must not span multiple segments!
• translate5:maxNumberOfLines must refer to the lines in a single segment only!
  • How many lines a segment (not a trans-unit) should maximally have
  • If maxNumberOfLines is set,
    • maxWidth refers to the length of each line, otherwise maxWidth refers to the trans-unit
    • minWidth refers to the length of each line, otherwise maxWidth refers to the trans-unit

  • • Trans-units must not span multiple segments

  then

  • • !
      

Settings for pixel-mapping

The mapping of characters and their pixel-lengths can be given:

• • • If you need maxNumberOfLines to span multiple segments, contact translate5s development team

• For pixel-based length check:
  • For each character for a certain font and a certain font-size the pixel-width
    
    • Definitions in pixel-mapping.xlsx
• or in import-XLF-files;
• default values are set in the config.

Each segment will check if there is a specific mapping for its import-file. If settings for the file do not exist, the general task-settings are used. If those don't exist, the config is used.

Example for pixel-mapping.xlsx:

Trans-Unit

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).
  This is because 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.

Task Template

see Task Templates

Default Config

• • Font-size and used font of current task
    • Would be possible to overwrite them in xliff 1.2, yet this is not yet implemented (ask translate5s development team, if you need it)

Special settings for pixel length restriction

For pixel-based length check to work pixel length of single characters has to be defined:

• in translate5s system configuration 
• in the pixel-mapping.xlsx

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.

They are used 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 find an example for pixel-mapping.xlsx below.

Explanation of columns in pixel-mapping.xlsx

• font: Contains the font-name as define in runtimeOptions.lengthRestriction.pixelmapping.font
• fontSize: Contains the font-size as defined in runtimeOptions.lengthRestriction.pixelmapping.fontSize
• 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 for 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

View file
name pixel-mapping.xlsx height 250

Definitions in xliff 1.2

(overwrite corresponding definitions in the configuration)

Please see "Definable parameters" for explanation.

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.