# Release Notes - Okapi XLIFF Toolkit 1.1.6, Jul-29-2017

- Overview
- Requirements and Installation
- Documentation
- Support
- Validation
- Prefixes for Fragment Identifiers
- ITS Support

## Overview

This package provides a library that implements the XLIFF 2.0 OASIS Standard.

This library is under Apache 2.0 license and the source code for this package is hosted in the Okapi XLIFF Toolkit project.

This distribution includes:

- `okapi-lib-xliff2-<version>.jar` - Java library that includes an XLIFF reader class, an XLIFF writer class, and various helper classes to manipulate XLIFF data.

- This library has no dependency. This is the only file you need if you are using the library with your own application.
- You can also get this JAR from the project's Maven repository at http://repository-okapi.forge.cloudbees.com/release/.

- `lynx.jar` - A tool to test and perform various manipulation of XLIFF documents.
- `lynx.bat` - A batch file to run Lynx (for Windows).
- `lynxPrompt.bat` - An helper batch file used by startLynxPrompt (for Windows).
- `startLynxPrompt.bat` - A Windows batch file to start a DOS prompt where you can call Lynx from any folder.
- `lynx.sh` - A Bash shell script to run Lynx (on Linux and Macintosh).

### Lynx

Lynx is a command-line tools that can performs validation and a few other tasks on XLIFF 2 documents.
It also implements short examples of code that illustrate specific aspects of the library and demonstrate conformance (See conformance-notes.html for details).

When started without parameters, Lynx opens a dialog box where you can validate a document.

Note that you can also perform validation on-line here: http://okapi-lynx.appspot.com/validation.

In Windows, to start a DOS prompt from where you can call Lynx, just double-click on `startLynxPrompt.bat`

- The command `-v` validates the XLIFF document against the XLIFF 2 schemas and performs the processing validation.
- The command `-r` reads the XLIFF document and display the parsed components.
- The command `-rw` reads the XLIFF document and re-write it.

- The option `-rd` removes the original data of the inline codes.
- The option `-ra` removes the inline annotation markers (`<mrk>`/`<sm>`/`<em>`).
- The option `-rx` removes the extension elements and attributes (not touching the skeleton content).
- The option `-rm <nsSuffix>` removes all elements and attributes for the module ending with `<nsSuffix>`. Use `-rm all` to remove all modules.
- The option `-pseudo` creates basic pseudo-translations from the source (existing translations are overwritten). The transformation is done as follow: digits are replaced by 'N', Ctrl+A by 'A', the letters 'A' and 'a' by a Ctrl+A, other letters by 'Z'.
- The option `-join1` removes all segmentation breaks in each unit (except the segments with `canResegment='no'` (Modifier mode)).
- The option `-join2` removes all segmentation breaks in each unit (even the segments with `canResegment='no'` (Merger mode)).
- The option `-seg` applies basic re-segmentation to each existing segment (breaks after the sequence period + whitespace). To re-segment a unit already segmented use `-join1` and `-seg` at the same time.

- The command `-fr` finds a reference in the input file.

- The option `-prefixes path` allows the user to provide the path of a properties file with additional prefixes for URI fragment identification.

- The command `-vr` verifies the syntax of the `ref` attributes in the annotations of in the input file.

- The option `-prefixes path` allows the user to provide the path of a properties file with additional prefixes for URI fragment identification.

- The command `-lp` lists all extensions/modules prefixes allowed in fragment identifiers.

- The option `-prefixes path` allows the user to provide the path of a properties file with additional prefixes for URI fragment identification.

- The command `-pvr` processes the validation rules of any `<validation>` element found in the document.

- The option `-prefixes path` allows the user to provide the path of a properties file with additional prefixes for URI fragment identification.

- The command `-html` reads the XLIFF document and creates an HTML simple output from it.
- The command `-x` lists all examples available.
- The command `-x<N>` (where `<N>` is a number) outputs the example of the snippet with that number. Use `-source` to show the corresponding source code.
- The option `-trace` enable the display of the exception stack when an error occurs.
- Calling the application without parameter opens a dialog box from where you can select (or drag and drop) a document and validate it.

For example (assuming Windows command-line and the distribution directory):

- To validate a document, type:

>     lynx samples/example.html.xlf

- To segment and pseudo translate a document, type:

>     lynx -rw -seg -pseudo samples/example.html.xlf

- To execute the example 6 and display its source code, type:

>     lynx -x6 -source

- To remove all extensions as well as the Format Style module from a document, type:

>     lynx -rw -rx -rm "fs:2.0" myFile.xlf

- To display the parsed parts of the `hello.html.xlf` document, type:

>     lynx -r samples/hello.html.xlf

- To find the element corresponding to the reference `"#f=f1/u=tu1"` (i.e. the unit with id=tu1 in the file id=f1), type:

>     lynx -fr #f=f1/u=tu1 samples/hello.html.xlf

- To get a complete list of the tool's command and options, type:

>     lynx -?

## Requirements and Installation

### Requirements

- Java 1.7 or later.

### Installation

To install the library:

1. Simply unzip the distribution in the directory where you want to use it.

### Uninstallation

To uninstall the library:

1. Simply delete the jar file from your directory.

## Documentation

The documentation of the library is available in the documentation sub-directory.

See also the online Getting Started guide.

## Support

If you have questions, suggestions or bug to report, you can do this different ways:

- To read more about XLIFF and provide feedback or ask questions regarding the format, use one of the XLIFF mailing lists:
  - http://lists.oasis-open.org/archives/xliff/ (anyone can read, only XLIFF TC members can post).
  - http://lists.oasis-open.org/archives/xliff-comment/ (anyone can read, anyone can register to post).
  - http://lists.oasis-open.org/archives/xliff-users/ (anyone can read, anyone can register to post).
- To get the source code, and post bug reports or request for enhancement, use the project site.
- To get help with the tool or discuss it in general, use the Okapi Tools users group (anyone can read, anyone can register to post).

## Validation

Important notes on what validation the library performs:

- The content of non-implemented modules and extensions are not validated beyond the schema validation.
  (For example the XLIFF elements in the Change Tracking module `<revision>` elements are only validated against the schema, not for processing requirements or constraints not enforced in the schema). This is because as far as the library is concerned they are part of the extension elements.

## Prefixes for Fragment Identifiers

The list of prefixes allowed in fragment identifiers is stored in the `prefixes.properties` file in the JAR file of the library.

See the Fragment Identifier Registration page for details and the list of all registered prefixes.

The option `-prefixes path` allows the user to provide the path of a properties file with additional prefixes for URI fragment identification. Those custom prefixes are added to the default ones. Note that you can have more than one namespace associated to a single prefix.

The format of the custom prefixes file is the same as the default one:

- Java properties file format as described in http://docs.oracle.com/javase/7/docs/api/java/util/Properties.html#load(java.io.Reader)
- each entry is in the form: `<namespace-uri>=<prefix>`
- One entry per line.
- Comment lines have a character `'#'` or `'!'` as the first non-white space character.
- Do not forget to escape literal characters such as `':'`, `'='`, or `'\'` in the URI. See the Java documentation for the full list.

To modify the default `prefixes.properties` file in the library JAR file:

- Extract the properties file from the JAR file.
- Add or remove the pairs.
- Add the modified properties file in the JAR, overriding the existing one.

## ITS Support

As of this release of the toolkit, an effort to map and create a module for the Internationalization Tag Set 2.0 is in progress.

- ITS 2.0 Specification: http://www.w3.org/TR/its20
- XLIFF 2.0 and ITS 2.0 mapping page: http://www.w3.org/International/its/wiki/XLIFF_2.0_Mapping

The following data categories are supported through a specialized API:

- Domain
- MT Confidence
- Terminology
- Text Analysis
- Provenance (with some restrictions currently)
- Localization Quality Issue (with some restriction currently)

See the documentation for IWithITSAttributes and IWithITSGroups for details.

Other data categories can be access using the extension API.