The Bilingual File Parser

The bilingual parser extracts localizable content from bilingual documents. Unlike a native parser, which extracts source content only, a bilingual parser can set both source and target content and group that content into paragraph units and segments.

Writing a bilingual parser

When you build a filter with the Bilingual API, the parser must implement IBilingualParser. In practice, the parser also participates in the bilingual content-processing pipeline through IBilingualContentProcessor.

You may also need to implement additional types, such as INativeContentCycleAware and ISettingsAware.

The simplest approach is to derive from AbstractBilingualFileTypeComponent and implement IBilingualParser and INativeContentCycleAware. This base class provides helper properties and methods that reduce the amount of code you need to write.

INativeContentCycleAware gives the parser access to information such as the original file path, source and target languages, and encoding. It also provides methods that the framework calls at key stages of parsing so that your filter can initialize and clean up correctly. If the parser uses settings, implement ISettingsAware and provide a UI for those settings. For more information, see Filter UI Settings.

Using AbstractBilingualFileTypeComponent

The AbstractBilingualFileTypeComponent base class already implements IFileTypeComponentBuilder and IBilingualFileTypeComponent. This leaves your parser to implement the members required by IBilingualParser, IParser, and INativeContentCycleAware.

Implementing IBilingualParser

The IBilingualParser interface defines two essential properties.

IBilingualParser.DocumentProperties

The DocumentProperties property holds an IDocumentProperties instance. The Bilingual API sets this property during parser initialization. You store the value and then use it to set the source and target languages and initialize the output stream.

IBilingualContentProcessor.Output

The Output property is of type IBilingualContentProcessor. The framework initializes it and uses it to connect the bilingual parser to the content processors further down the processing chain during extraction from a bilingual file format to the default bilingual SDLXLIFF (*.xliff) persistent format.

To support streaming and avoid loading the entire document into memory, the parser should feed paragraph units one at a time through Output.ProcessParagraphUnit(). Before it processes any paragraph units, it must also provide document and file properties through Output.Initialize() and Output.SetFileProperties().

Output.Initialize()

Call Initialize to pass the DocumentProperties object for the current document. Do this after you set SourceLanguage and TargetLanguage from the source file.

Note

This method should always be called before any other call on the Output interface.

Output.SetFileProperties()

Call SetFileProperties to provide the framework with the properties for each file in the document. Call it before you process the file's paragraph units through ProcessParagraphUnit.

SetFileProperties() takes an IFileProperties instance. The bilingual parser must create this instance, typically by using CreateFileProperties. In most cases, the parser should also set the IPersistentFileConversionProperties property before it passes the object to SetFileProperties(). When your parser implements INativeContentCycleAware, you can usually obtain this information from the file properties that the framework passes into the content cycle. You may also need to set other values on IFileProperties, such as the source language, target language, tool name, tool version, and creation date.

Output.ProcessParagraphUnit()

Call ProcessParagraphUnit for each paragraph unit in the source file. Create the IParagraphUnit instance by calling CreateParagraphUnit. When you create a paragraph unit, specify the source language, target language, and lock type. In most cases, paragraph units are either structure paragraph units with the Structure lock type or translatable paragraph units with the Unlocked lock type.

Output.FileComplete()

Call FileComplete after you process all paragraph units in a file. After you call FileComplete(), do not change the file properties.

Output.Complete()

Call Complete after you process all content in all files. After you call Complete(), do not change the document properties.

Implementing IParser

IParser.OnProgress

The IParser interface defines an OnProgress event of type ProgressEventArgs. Use this event to notify the framework, and therefore the user, about parsing progress. In most cases, you should raise it with 0 before you open a file, update it with the current percentage during parsing, and raise it with 100 when parsing is complete.

IParser.ParseNext()

The IParser interface also requires the ParseNext method. The framework calls this method repeatedly to process the next chunk of input from the source bilingual document.

The implementation should parse a suitable chunk of input, preferably a small one, and return a Boolean value that indicates whether more work remains. Return false when the parser has processed all file content.

Typically, this method, or methods that it calls, invoke the Output property methods to report the source file content to the framework.

Implementing INativeContentCycleAware

If your parser implements INativeContentCycleAware, it must implement the following three methods.

SetFileProperties()

The standard implementation of SetFileProperties stores its IFileProperties parameter in a class field. The bilingual parser can then use these file properties to supplement information from the source file, such as the original encoding.

StartOfInput()

The framework calls this method after component initialization, including SetFileProperties, but before it parses and passes any content to File Type Support Framework components.

EndOfInput()

The framework calls this method after it finishes processing the bilingual content.

Implementing ISettingsAware

If your parser implements ISettingsAware, it must implement the following method.

InitializeSettings()

InitializeSettings passes an ISettingsBundle object and a configurationId (FileTypeConfigurationId). Use these values to populate the settings object that the parser requires:

• C#

public void InitializeSettings(Sdl.Core.Settings.ISettingsBundle settingsBundle, string configurationId)
{
    UserSettings _userSettings = new UserSettings();
    _userSettings.PopulateFromSettingsBundle(settingsBundle, configurationId);
    LockPrdCodes = _userSettings.LockPrdCodes;
}

See also

• The File Parser

Note

This content may be out-of-date. To check the latest information on this topic, inspect the libraries using the Visual Studio Object Browser.