help.axcms.netAxinom Logo
Save Save Chapter Send Feedback

Page Translation System

 

Goals and requirements

The page translation system enables end-users to send pages to an external system for translation in an XML format. AxCMS.net uses a translation module as a gateway to the external system. The page translation system is still operational without the module - it simply gives the XML output to the user for manual translation.

Page import from the external system is not covered. This must be carried out by either the translation module itself or manually by the user.

The translation module decides which languages a page can be translated to, if a translation module is used. This is generally used to detect and avoid duplicating the original language. Otherwise, pages can be translated to any language that is supported by any resource manager aside from the "CMS" resource manager, including whichever language the page is in (since this is not known by AxCMS.net).

The XML format is the standard page import/export format used by AxCMS.net.

On translation, AxCMS.net creates language-specific copies of pages. In a translation module is used, it can set up relations and do other post-processing on created pages. If a translation module is not used, the user can choose which circle relations to set up between the pages. The pages may already exist in either case - existing content is not overwritten.

Users need to be able to create new pages in order to use the page translation system.

The user will see the list of pages involved in the translation operation.

Architectural description

The page translation system consists of four logical components:
• the user interface;
• the export interface;
• the translation module; and
• the translation facade for the user interface.

The user interface is a popup page which can be invoked from the page detail form of an existing page. It uses the translation facade for all of its interactions with the page translation system. It knows about the export interface and will direct users there when appropriate.

The translation facade represents the translation system in a form suitable for consumption by the user interface. It executes the page translation workflow and interfaces with the translation module.

The translation module is an optional component. It is created by a factory class. The type of the translation module is specified in the configuration file.

The export interface is a custom HTTP handler which takes a set of page IDs and generates the XML for the given pages.

Design details

Project-specific logic

The translation module is project-specific and contains all project-specific page initialization logic. It is given the original page and set of copy pages after all copy pages have been created by AxCMSnet. To implement translation module, implement IPageTranslationModule interface.

 /// <summary>
 /// An interface for a module which takes language-specific copies of pages and carries out a
 /// translation process on them. The interface provides means to signal the module to begin
 /// translating a specific set of pages. The implementing classes will determine the names of the
 /// language-specific copies of the original page.
 /// </summary>
 public interface IPageTranslationModule
 {
  /// <summary>
  /// Returns the name of a copy page in a specific language.
  /// </summary>
  /// <param name="originalName">The original name of the page.</param>
  /// <param name="languageCode">The code of the language that the copy is to be translated into.</param>
  /// <returns>The name of the copy page in the given language.</returns>
  /// <exception cref="ArgumentNullException">Thrown if <paramref name="originalName"/> is null.</exception>
  /// <exception cref="ArgumentNullException">Thrown if <paramref name="languageCode"/> is null.</exception>
  /// <exception cref="ArgumentException">Thrown if a copy page name cannot be
  /// generated for the given input parameters.</exception>
  string GetCopyName(string originalName, string languageCode);


  /// <summary>
  /// Gets the language codes of all languages the module can translate the given page into.
  /// </summary>
  /// <remarks>
  /// The list must not contain duplicates.
  /// </remarks>
  IEnumerable<string> GetLanguageCodesOfPossibleTargetLanguages(AxPageBase originalPage);


  /// <summary>
  /// Gets the types of circle relations that should be created between copy pages and the original.
  /// </summary>
  /// <remarks>
  /// The list must not contain duplicates.
  /// </remarks>
  CategoryCollection TypesOfRelationsToCreate { get; }


  /// <summary>
  /// Instructs the module to begin translating a set of pages.
  ///
  /// The translation process may occur synchronously but the interface
  /// only concerns starting the translation process.
  /// </summary>
  /// <remarks>
  /// The set of pages to translate will include the original and copies for
  /// any languages that are to be translted. The copy pages are guaranteed to
  /// use the names returned by <see cref="GetCopyName"/>.
  ///
  /// The original page is not guaranteed to use the same name the module
  /// was given in <see cref="GetCopyName"/>.
  /// The set of languages is not guaranteed to be the union of all the languages
  /// <see cref="GetCopyName"/> was called with. It may be a subset of the union.
  ///
  /// The original page will be the first page in the XML document.
  /// </remarks>
  /// <param name="serializedPages">The XML form of the serialized set of pages</param>
  /// <returns>A message to give to the user as feedback.</returns>
  Message BeginTranslation(XmlDocument serializedPages);


  /// <summary>
  /// Instructs the module to perform any project-specific initialization of copy pages.
  /// </summary>
  /// <remarks>
  /// Copy page creation is atomic. If the initialization fails, no copy pages are created.
  ///
  /// This is called after all copy pages have been created and all default content copied.
  /// This includes:
  /// * page content
  /// * meta tags (except language, for obvious reasons)
  /// * the contents of the Details property
  ///
  /// All relations specified by the translation module will have been created.
  ///
  /// NOTE: the copy pages might not be newly created pages - they could have existed beforehand.
  /// </remarks>
  void InitializeCopyPages(AxPageBase originalPage, IEnumerable<AxPageBase> copyPages);
 }

The type of the active page translation module is configured by the PageTranslationModuleTypeName setting in the AppSettings configuration section. The full type name should be specified here.

<add key="PageTranslationModuleTypeName" value="Across.AcrossModule, Across"/>

As said, page import from the external system is not covered. This must be carried out by either the custom code or manually by the user. Recommended approach for automation is to write AxCMS.Service task, that will repeatedly check if the translation is ready, then use Axinom.AECMS.Import.TranslationPageImporter to import translated pages.