Processing custom project package formats

Trados Studio Integration API provides support for third-party developers to transform third-party packages into a format that Trados Studio can work with. This page will describe the steps required to create a custom package converter.

Declaring a custom package converter

The first step in creating a custom package converter is the declaration:

Create a class that implements IExternalPackageConverter interface and provide specific implementations for the following methods:

Method Name	Description
`ConvertPackage`	This method allows implementing logic that will transform a third party package format into a format recognised by Trados Studio.
`ConvertReturnPackage`	This method allows conversion from the Trados Studio return package format into the third party package format.

Decorate the class with the ExternalPackageConvertorExtension attribute.

Property	Description
`Id`	Unique identifier for the converter. To avoid confusion with other third party plugins we recommend using a combination of the project namespace and class name.
`Name`	Name of the converter
`Description`	Description for the converter
`PackageFileFilter`	The filter to be used by the Windows OS File Opener dialog. This allows the user to see only files that match the given extension and thus pick a valid file.
`PackageFileExtension`	The file extension of the package to be imported into Trados Studio.
`ReturnPackageFileExtension`	The file extension of the return package.

The bellow sample provides a visual to the elements described above:

[ExternalPackageConvertorExtension(
    Id = "Sdl.ProjectsOperations.Sample.SamplePackageConverter",
    Name = "Sample Package Converter",
    Description = "Sample Package Converter",
    PackageFileFilter = "Sample Packages (*.zip)|*.zip",
    PackageFileExtension = ".zip",
    ReturnPackageFileExtension = ".zip")]
public class SamplePackageConverter : IExternalPackageConverter
{
    public SamplePackageConverter()
    {
    }

    public PackageConversionResult ConversionResult {get; private set;}

    public event EventHandler<PackageConverterMessageEventArgs> PackageMessage;
    public event EventHandler<ConvertExternalPackageEventArgs> PackageConverted;

    public void ConvertPackage(IConversionContext context, ExternalPackageConversionInfo externalPackageConversionInfo)
    {
        // your costum logic here
    }

    public void ConvertReturnPackage(IConversionContext context, ExternalPackageConversionInfo externalPackageConversionInfo)
    {
        // your custom logic here
    }
}

Note

The Open Package and Create Return Package wizard's Data object is available in the custom package converter as well, via the ExternalPackageConversionInfo.CustomData property, allowing third party developers to use inside the converter data that has been captured in their custom wizard pages .

Importing a custom package

Importing a custom package is done by implementing the ConvertPackage(IConversionContext context, ExternalPackageConversionInfo externalPackageConversionInfo) method. The usual steps within the implementation are as follows:

Unzipping the package

Creating an IPackage object by calling the IConversionContext.CreatePackage method. The parameters required here are as follows

Parameter Name	Description
`projectName`	The name of the final project to be imported.
`sourceLanguage`	The source language of the project to be imported.
`createdAt`	The `DateTime` creation details.
`createdBy`	The user who created the package.
`originalProjectGuid`	Pass this as `Guid.Empty` if this is the first time the project is imported into Trados Studio, otherwise pass the original project id. The presence of the project in Trados Studio can be determined by calling IConversionContext.CheckForExistingProject()

Adding the resources to the package IPackage object such as: files, translation memories, termbases, specific settings
Physically packaging the package into Trados Studio valid format by calling IPackage.Pack() and specifying the location where the package will be saved.
Performing cleanup on temporary resources used, such as files.

public void ConvertPackage(IConversionContext context, ExternalPackageConversionInfo externalPackageConversionInfo)
{
    OnPackageConverted(0, "Beginning conversion");

    try
    {
        var projectId = Guid.Empty;              
        var package = context.CreatePackage("SampleProject", 
                    new Language("en-us"), DateTime.Now, "sample_api", projectId);

        AddResourcesToPackage(package);

        package.Pack("C:\\SampleLocation\\sample_package.sdlppx");
    }
    finally
    {
        Cleanup();
    }
     
    OnPackageConverted(100, "Conversion Completed");
}

Exporting a return package into a custom format

Exporting a return package into a custom package is done by implementing the ConvertReturnPackage(IConversionContext context, ExternalPackageConversionInfo externalPackageConversionInfo) method. The usual steps within the implementation are as follows:

Creating an IPackage object from the return package file by calling the IConversionContext.OpenPackage method.
Extracting the necessary resources from the IPackage object and creating the custom return package.
Performing cleanup on temporary resources used, such as files.

public void ConvertReturnPackage(IConversionContext context, ExternalPackageConversionInfo externalPackageConversionInfo)
{
    OnPackageConverted(0, "Beginning conversion");

    try
    {
        var fromPackage = context.OpenPackage(externalPackageConversionInfo.FromPackagePath);

        CreateCustomReturnPackage(fromPackage);
    }
    finally
    {
        Cleanup();
    }

    OnPackageConverted(100, "Conversion Completed");
}