The File Writer

The last step in the localization workflow is the generation of the (translated) target file in the original document format. In one of the examples provided in this SDK we need to write all translated segments from a bilingual SDLXliff document to a (native)SubRip file. This task is performed by a Native API Writer.

When implementing a Native API file writer you must derive your writer class from the interfaces INativeFileTypeComponent and INativeFileWriter. These interfaces provide a way of connecting to the File Type Support Framework and allowing it to initialize the writer with the objects it needs to interact with the File Type Support Framework. A writer will also normally derive from the INativeOutputSettingsAware, INativeContentCycleAware and ISettingsAware interfaces, which provide the writer with additional information such as the target file path name, the target language and the preferred encoding of the target file and also allow any required settings to be populated.

However, the simplest way to implement a native writer is to merely derive it from the AbstractNativeFileWriter class and the INativeContentCycleAware interfaces, and use the helper functions of the AbstractNativeFileWriter class.

The AbstractNativeFileWriter base class provides an implementation of the INativeFilterComponent, IAbstractNativeContentHandler and INativeOutputSettingsAware interfaces leaving only the INativeContentCycleAware interface to be implemented by the derived class. If this AbstractNativeFileWriter class is used as a base class, in its implementations of IAbstractNativeContentHandler it provides some default (empty) implementations of the interface methods. These public virtual methods can be overwritten in the derived class if an implementation is required for a particular native writer.

You may have noticed that the IAbstractNativeContentHandler interface, from which the Native API writer is derived, is the same interface that is used for the Output property of the AbstractNativeFileParser base parser class. The reason for this is that all text, tags and other mark-up items that are written during the parsing phase are re-used when the translated output file is being creating, with the mark-up order and translated text content determined by the translation process. However, the translated document will only contain tags that were created during the parsing phase. The Native API writer can rely on the tag content of each tag to be the same as it was when it was written by the parser with the exception of any manually-added mark-up items in a framework-based editor. If a filter allows for manually created mark-up such as Bold, Italic or Underline formatting added by the user during translation, then this will be defined in the File Type Component Builder. The only other exception to this is when the parser class has created a tag with localizable content in it. If this is the case, then the LocalizableContent property of the tag properties must be examined to retrieve the text for the localizable sub-segments.

The AbstractNativeFileWriter base class provides some default virtual implementations of the IAbstractNativeContentHandler interface methods that represent tags, text and futher mark-up item in the translated document. Therefore, in your derived Native API writer class, you only need to implement the overridable methods for the text or mark-up that is applicable to your document type. A list of overridable methods is provided below. If however, you are not deriving from AbstractNativeFileWriter, you will need to implement all of the following methods, even if the method content is empty.

• StructureTag: This method is called on the Native API writer class when structure tag information is being sent to the writer class. Your implementation (if any) will need to interpret the IStructureTagProperties.TagContent string that was set by the parser. A simple, text- based file format parsers may only need to write the tag content to the output file.
• InlineStartTag: This method is called by the framework when paired start tag information is being sent to the writer. Again, a simple implementation may only need to write the tag content to the output file.
• InlineEndTag: This method is called by the framework when the end tag of a pair of tags is being sent to the writer. The framework guarantees that all tag pairs will remain well formed during the translation process.
• InlinePlaceholderTag: This method is called by the framework when single placeholder tag information is being sent to the writer. Text: This method is called by the framework to tell the writer class to write text in human readable form to the output file. This will usually be the translated text, but it could also be the source text when previewing the source document.
• CustomInfo: This method is for sending temporary custom information that can be used for communication between native content processing components.
• ChangeContext: This method is normally invoked on the Output property of the Native API parser, and is not expected to be used by the writer. However, it still needs to be defined, as it is part of the common IAbstractNativeContentHandler interface used by both the parser and writer.
• Dispose method: This method is implemented in AbstractNativeFileWriter and can be overridden by subclasses. This method is explicitly called after an unhandled exception is thrown in the Filter Framework. This is the last chance for the filter to release acquired resources (managed and unmanged). This can happen when: - Acquire resources in StartOfInput() and release them in EndOfInput() - Acquire resources in BeforeParsing() and release them in AfterParsing() - Acquire resources in SetFileProperties() and release them in FileComplete() - or other similar situations.

The AbstractNativeFileWriter interface contains two further methods that need to be implemented in any writer class. These are outlined below:

• SetFileProperties: This method receives a IPersistentFileConversionProperties object. StartOfInput: This method is called by the framework after component initialization (i.e. after * SetFileProperties(), but before any content is parsed and passed to any of the filter components.
• EndOfInput: This method is called by the framework after processing of the native (monolingual) content has finished.

The ISettingsAware interface contains one method that needs to be implemented in any writer class, which requires access to any settings the writer may need. This is shown below:

• InitializeSettings method: Passes in an ISettingsBundle object and a configurationId FileTypeConfigurationId. These can be used to populate the required settings object used by the writer, e.g.:

• C#

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

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.