Specifies the M5 Content Translation Support App resulting from migrating the M4.5 Content Translation Support module.

Introduction

Per discussion with Philipp, we plan to migrate the M4.5 Content Translation Support (CTS) module to M5 as an App. Here is a mockup of what the UI will look like:


The advantages of migrating the CTS module to M5 as a Content App are:

  • More familiar user experience for M5 users, because M5 users will be familiar with using Content Apps.
  • More straightforward to develop in M5, because the M5 Content App framework can be leveraged.
  • More conducive to enhancements in the future, because we might want to add features in the future such as highlighting those pages in the tree that require new translation.

We do not plan to add any enhancements as part of the current migration, only to reproduce the M4.5 functionality while having a design that is conducive to future enhancements. See the section Ideas for Future Enhancements for a list of possible future enhancements.

The disadvantages of migrating the CTS module to M5 as a Content App are:

  • It changes M4.5 CTS UX that users of M4.5 may have already become accustomed to.

Specification

What actions are in the Action Bar?

  • Export translation in the Translation File actions group
    • This will only be enabled when a single page is selected in the tree
    • This will open a dialog similar to the top half of the M4.5 CTS UI
    • Use icon icon-export
  • Import translation action in the same Translation File actions group
    • This will always be enabled, regardless of whether one, multiple, or no pages are selected in the tree
    • This will open a dialog similar to the bottom half of the M4.5 CTS UI
    • Use icon icon-import
  • Preview page action in the Preview group
    • It will only be enabled when a single page is selected in the tree, same as in Pages App
    • It will cause the page to open in a Pages App tab in preview mode 
    • This should be the default action when double clicking on a page in the tree
  • Publish page, Publish incl. subpages, Unpublish page actions in the Publish group
    • These are the same as in Pages App

What should the Export Translation dialog look like and do?


  • The file format options need to be calculated dynamically based on the module's configuration in Config:/modules/content-translation-support/config/exporters
  • Field labels should be right aligned and appear to the left of the field.
  • Make sure that the single mandatory field is marked with a black * with space between it and the label.
  • Do not forget the help text, which is "Download a file containing all translatable content in the selected page and its subpages. Technically, the file will contain all content nodes in the selected page and its subpages marked as i18n in the content definition."
  • System save file dialog should set the filename appropriately.
  • Clicking "EXPORT FILE" button should execute the browser's save file process.
  • The action is to download the translation texts for the selected page and all its subpages.
    • Note: These also need to be calculated dynamically based on what is in Config:/modules/content-translation-support/config/controlTypesToExport and Config:/modules/content-translation-support/config/nodeDataToTranslateFinder
  • Per convention, there is no message displayed after dialog is closed and action completes successfully.

What should the Import Translation dialog look like and do?


  • Have a drag/drop field for the file labeled "File to import" like the field in the Import dialog.
  • The file format options need to be calculated dynamically based on the module's configuration in Config:/modules/content-translation-support/config/importers
  • Have a checkbox for "Overwrite already existing translations", unchecked by default
  • Have a checkbox for "Also import empty translations", unchecked by default
  • Field labels should be right aligned and appear to the left of the field.
  • Make sure that the mandatory fields are marked with a black * with space between it and the label.
  • Do not forget the help text, which is "Imports all texts in the file you upload. The import affects only those pages referenced in the file."
  • Check there is a progress bar in the file import field when importing the file (but the dialog box is not yet closed).
  • Check the blue info notification appears when file is successfully selected (but the dialog box is not yet closed). It should say "You file has been uploaded successfully".
  • Check the yellow warning notification appears when file upload is aborted. It should say "You have aborted the upload of your file".
  • If no file is selected when the Import File button is pressed, the dialog should not validate, and the field should be marked in red as in normal dialog validation.




  • If a file is selected, the dialog should close and a yellow confirmation dialog should ask the user to confirm the import
    • If the filename is a path, then the message in the confirmation dialog should say the root page node being updated: "</path/to/page> and all its subpages will be updated."
    • If the filename is not a path, then the message in the confirmation dialog should be generic: "All pages referenced in <filename> will be updated."
  • Per convention (see Import action in the Pages app), there is no message displayed after the confirmation dialog is closed and action completes successfully.
  • If import action completes successfully and filename is a path, the tree should expand to show and select the page referenced by the filename as the root page that was updated by the import. This causes previous selections in the tree to be lost. 
    • If the filename is not a path, do nothing.

What should export error reporting be?

  • Should use alert message of the system that is a modal dialog and requires confirmation.
    • See the modal dialog box that appears when you try to move a node inside itself in the Pages App. It is red and requires the user to close it.
  • We do not anticipate any non-runtime errors during export except runtime errors.
    • The error title should always be "Export translation file failed".
    • The error description should be based on the message from the caught exception.

What should import error reporting be?

  • This describes errors that occur after the user confirms the import confirmation dialog. The only error that can occur are validation errors due to not inputing a file in the import dialog.
  • Should use alert message of the system that is a modal dialog and requires confirmation.
    • See the modal dialog box that appears when you try to move a node inside itself in the Pages App. It is red and requires the user to close it.
  • What import errors can occur and what should their corresponding error messages?
    • By default, the error title should be "Import translation file failed" and error description should be the exception message.
    • Wrong file format detected when file imported. 
      • If this error can be isolated, error title should be "Import translation file failed due to invalid file format" and error description should be the exception message.
      • Note: M4.5 does not report a sensible error message right now and reports the exception message. 
    • Wrong column names, except language code column names.
      • If this error can be isolated, error title should be "Import translation file failed due to invalid column name" and error description should be the exception message.
      • Note: M4.5 does not report a sensible error message right now and reports the exception message. 
    • Wrong language code in column title.
      • If this error can be isolated, error title should be, for example, "Import translation file failed due to invalid locale name"  and error description should be the exception message.
      • Note: M4.5 does not report a sensible error message right now and reports the exception message.
    • Any other cases, use the default.

What does the browser workbench look like?

  • Only tree view, no other views.
  • No search or list view for the migration for now, perhaps support later as enhancements.
  • Include all columns in the tree view in Pages App: page, title, template, status, modification date.
  • What should the checkbox behavior be?
    • If one single thing selected, everything is enabled: export action, import action, preview action.
    • If none or multiple selected, then the only thing enabled is the import action, everything else is disabled: export action, preview action.
    • The thing that is downloaded are the fields to translate from the single selected pages and all its sub-pages.
    • Note : This is in accordance with the behavior of the Pages App.

How should the CTS App icon appear in the Shell?

  • It should be placed in the Tools group, after Cache Tools, before About Magnolia.
  • It should be called "Content Translation".
  • Use the following App icon: 022_language-app

What does the module configuration tree look like?


  • config/importers should be the same.
  • config/exporters should be the same.
  • config/controlTypesToExport will list the controls to translate.
    • We will use class name, for example info.magnolia.ui.form.field.definition.TextFieldDefinition, for the value rather than a shortened name such as edit as in M4.5. This is because M5 no longer uses the same names for the controls as M4.5 per the online documentation (see M5 Fields Documentation and M4.5 Controls Documentation). Also a user will know the classname based on the online documentation, for example see M5 Text Field Documentation.
  • config/nodeDataToTranslateFinder should be the same.
    • We must modify the info.magnolia.module.contenttranslationsupport.export.STKDialogBasedNodeDataToTranslateFinder class to support new way in M5 to identify fields with i18n support.
  • commands will be included for use with the scheduling module, but there will be additional import and export commands used by the new dialogs.
  • apps will be added containing M5 configuration for the CTS app
  • dialogs will be added containing M5 configuration for the dialogs of the CTS app
  • pages will not be included and will be ignored if it exists, since it is M4.5 specific.

What should the translation file format be?

  • The format should be exactly the same as 4.5.
  • There is one small scenario in which the output may be different due to the new translation mechanism. In M4.5, if a dialog definition does not contain a label at all, then an empty string is output in the translation file. In M5, if there is no label at all, the key to use in the new i18n files is reported because the translation code considers the key to exist but the value to be missing. Therefore, sometimes in M5 this key is output for the dialog or field name whereas the empty string would have been reported in M4.5.

What should automatic migration from M4.5 be?

  • One can migrate by copying the configuration tree straight from M4.5 to M5 and then adding the apps and dialogs folders with the following small changes.
    • The migration needs to change the values under config/controlTypesToExport to use classnames for the fields to translate rather than the M4.5 shortened names for the controls.
  • (question) Do we need to create some kind of automated migration tool that does the above?

Questions

  • (question)  Do we need to create some kind of automated migration mechanism that copies and supplements the configuration tree from M4.5 to M5?

Ideas for Future Enhancements

  • Add dialog help text that is always visible once there is a way to do it in M5.3.
  • Action that only exports what has changed since the last imported translation
  • Highlight pages in the tree that needs translation to be updated
  • Possibly have the tree include nodes/properties within the pages that support translation and highlight those
  • Have columns in tree showing translation
  • Have preview functionality which is obviously needed, with preview tabs and actions like in Pages app, possibly with a preview action per language
  • More accurate timestamps on component level in the exported file
  • Support multiple selection for export for translation
  • Support search and list view for selecting things to export for translation
  • Use incremental error reporting for imported file once it is added to the field, field specific validation message in the dialog.
    • However, this check may be made difficult by the fact that the user can always select a different file format in the same dialog after selecting the file to import.
    • Due to the above, we would also have to guess at the type of the file in order to parse it to detect whether its contents are correctly formatted. 
  • For the translation update process after the import dialog is closed, show a progress bar and a final blue success message "New translations were imported successfully" if the process complete successfully.
    • (question) Is the integration process usually long enough to warrant this?
    • (question) What is another example of such a progress bar to model off of?
  • Workflow integration

Reference

 

  • No labels

9 Comments

  1. Andreas Weder

    Thanks for the concept page and the detailed UI design. I think it's important to do the two together to make sure we don't only do review and acceptance of the UI only once we've already implemented it. I thus truly appreciate your efforts.

    I've had a look at the mockups, not the concept itself. I like what I see, but still do have a couple of suggestions (smile). I'm adding them in comments below. I'll also answer some of the questions mentioned on the page regarding icons and the like after that.

    1. Andreas Weder

      Main UI

      My remarks (numbers correspond to call outs in the mockups below).

      1. Make title is more specific, mentions that it's about a "file", not an (abstract) "translation". The idea of titles is to always name the thing that the actions below affect as specific as possible. It also helps with the long actions names later on (see next point).

      2. Actions in the Action bar
        1. Since you've changed the title, you can shorten the action name. Also fits better on a single line.
        2. Add "upload" and "download" to the same group - the actions are similar and belong together

      3. It's not clear to me, what's actually being published here.
        Only the translations belonging to a page? Or always the entire page? This is especially important, if a page contains other changes as well. Do all of them get published along my translations as well? If they do, that's not necessary bad, but it should be made explicit.

      I'm assuming here, that a publication always publishes the entire page, and have changed the action name accordingly. I realize we don't do that elsewhere (e.g. we only say "publish" instead of "publish contact"), but that's actually wrong: we should always also mention what we publish/unpublish in other apps as well. So we can start with that here, also because it's a case where it's important to be explicit.

       


      1. Cheng Hu

        These suggestions have all been incorporated into the specification with the small change that we would still like to name the actions "Download translation file" and "Upload translation file", width permitting.

        Even if slightly redundant, we feel that this ensures there can be no confusion about what the actions do. 

    2. Andreas Weder

      Download a translation file

      My remarks

      1. I'd first explain what the action does in non-technical term in the introductory text, and move the more technical explanation to the help text, available on-click only. Mainly because I see the default users to be the translators, not some technical guys.

      2. Please use the default form layout here, where right-aligned labels are to the left of their input fields.
        1. Also mark the field as a required field (I know you can't select "nothing", but we should be consistent).

       


      1. Cheng Hu

        These suggestions have all been incorporated into the specification with the small change that we would like to make the dialog introductory text "Download a file containing all translatable content in the selected page and its subpages."

        We want to put emphasis on the fact that what is being processed is the page and its subpages. We also want to hint at the purpose of the file, which is to provide the content for translation.

    3. Andreas Weder

      Upload a translation file

      My remarks

      1. Good help text - it helps you understanding what the action does next.
        I'd make it available as always visible introductory text at the top, instead of in a help text available on-click only.

      2. Rearrange the items here: it's about a file upload, so specifying the file to upload should come first, followed by the format and the (optional) settings.
        1. Please also make sure you use the default form layout here (right-aligned labels on the left, input field on the right).
        2. Mark the required values with a star (it's black, btw - many devs use red).

      3. I've tried to make the options less technical and a bit more explicit. Are they actually correct still?

       


      1. Cheng Hu

        These suggestions have all been incorporated into the specification.

    4. Andreas Weder

      Answers to some questions you have

      Actions in the Action bar

      • Icon for download: 081-download
      • Icon for upload: 080-upload
      • Icon for app; we've already create one some time ago: 022_language-app

      On providing user feedback and reporting errors

      • I agree that we don't show a confirmation message when a download has concluded successfully.
      • On file upload, however, I'd typically do the following:
        • Once the file upload field has successfully uploaded the file, we show a quick notification at the top of the file upload file confirming that. This is possibly done already by the upload field itself, I don't know (it certainly should).
          • Similarly if the user aborted the upload, we show an red error notification message confirming this,
          • When an error occurred, the error should be shown in an alert, if possible, so it doesn't go unnoticed and has to be confirmed. Typically, unless the error is severe, there's no need to use an error message banner.
        • In general, we only use the red error message banner, if:
          • a severe error such as an exception occurred, that has to be logged in Pulse and might be of importance to other users as well. By default, send it to the user who triggered the action only.
            • typically, though, an error is never that severe: the ones you mentioned (e.g. bad column names and format) only require an alert, not a message banner.
          • (not applicable here) an error occurred in a background operation and while the user was working in another app
        • In general, try to validate things before you start the action.
          • If you detect anything wrong before you start, use an in-line form validation message to indicate the problem. Probably, by installing proper validators, this is done by the form automatically.
        • I suggest that you, once the user clicks on "upload file" in the dialog:
          • close the dialog
          • show a progress bar in an alert, if "installing" the new translation takes some time.
          • show a blue notification at the end confirming that "New translations were imported successfully."
          • if an error occurred, depending on the severity (see above), you might want to either show a red error alert or a red error message banner.

       

      Some questions that I have

      • (question) Wouldn't it be nice to be able to download more than a single translation file in one go?
        I'd pick the three pages I'm responsible for, then click on "download file"? Of course, you'd only be able to upload a single file a time.

      • (question) Why do you want to disable search?
        I'd love to be able to just enter a particular page name I want to translate, instead of looking for it in the page tree.

      1. Cheng Hu

        User feedback and error reporting
        • Success/failure notifications from the upload field itself is part of the current specification.
        • We have changed the specification to use an alert rather than a banner.
        • We do not currently plan on doing early validation on the file before the user has finished with the dialog because I think it would be difficult for us to guess what the file format is (since the user can always change their choice in the dialog) and therefor to parse it. However, I have added this as a possible future enhancement.
        • We do not currently plan on adding the progress bar and confirmation message for translation integration process as part of the migration. However, I have added this as a possible future enhancement.

        Answers to questions

        • I think this is a possible future enhancement and the current design is certainly conducive to it. However, we do not plan to do this as part of the migration.
        • I think this is also a possible future enhancement, but we do not currently plan to do it as part of the migration.