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
andConfig:/modules/content-translation-support/config/nodeDataToTranslateFinder
- Note: These also need to be calculated dynamically based on what is in
- 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.
- We will use class name, for example
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.
- We must modify the
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 appdialogs
will be added containing M5 configuration for the dialogs of the CTS apppages
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
anddialogs
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.
Do we need to create some kind of automated migration tool that does the above?
Questions
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.
Is the integration process usually long enough to warrant this?
What is another example of such a progress bar to model off of?
- Workflow integration
Reference
- M4.5 CTS module documentation
- MGNLCTS-31 - Getting issue details... STATUS
- MGNLCTS-33 - Getting issue details... STATUS
Overview
Content Tools
Apps
Activity
9 Comments
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
. 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.
Andreas Weder
Main UI
My remarks (numbers correspond to call outs in the mockups below).
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.
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.
Andreas Weder
Download a translation file
My remarks
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.
Andreas Weder
Upload a translation file
My remarks
I'd make it available as always visible introductory text at the top, instead of in a help text available on-click only.
Cheng Hu
These suggestions have all been incorporated into the specification.
Andreas Weder
Answers to some questions you have
Actions in the Action bar
On providing user feedback and reporting errors
Some questions that I have
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.
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.
Cheng Hu
Answers to questions