Doc: Add documentation for multi language function

Added description of the functionality in the Translation view as well
as a tutorial.

Task-number: QDS-5639
Change-Id: I839739058ce899c86080cf3dce7c26dc6fb83d64
Reviewed-by: Alessandro Portale <alessandro.portale@qt.io>
Reviewed-by: Thomas Hartmann <thomas.hartmann@qt.io>

5 files changed, 240 insertions, 2 deletions

diff --git a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
index cd6982b100..a66b9f5208 100644
--- a/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
+++ b/doc/qtdesignstudio/src/qtdesignstudio-toc.qdoc
@@ -44,6 +44,7 @@
                                 \li \l{Properties}
                                 \li \l{Connection View}
                                 \li \l{States}
+                                \li \l{Translations}
                                 \li \l{Transition Editor}
                                 \li \l{Timeline}
                                 \li \l{Curve Editor}
diff --git a/doc/qtdesignstudio/src/views/qtquick-designer.qdoc b/doc/qtdesignstudio/src/views/qtquick-designer.qdoc
index 22445c2550..f9f9ddb890 100644
--- a/doc/qtdesignstudio/src/views/qtquick-designer.qdoc
+++ b/doc/qtdesignstudio/src/views/qtquick-designer.qdoc
@@ -107,6 +107,11 @@
             the changes between states.
         \li \l{Animating Transitions Between States}
     \row
+        \li \l Translations
+        \li Provides functionality to add multi-language support to your
+        project.
+        \li \l{Translations}
+    \row
         \li \l Timeline
         \li Provides a timeline and keyframe based editor for animating
             the properties of components.
diff --git a/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc b/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc
index 66179af77a..021f4cddaa 100644
--- a/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc
+++ b/doc/qtdesignstudio/src/views/qtquick-states-view.qdoc
@@ -26,7 +26,7 @@
 /*!
     \page qtquick-states-view.html
     \previouspage qtquick-connection-view.html
-    \nextpage qtquick-transition-editor.html
+    \nextpage studio-translations.html
 
     \title States
 
diff --git a/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc b/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc
index 216e232d3f..e7d9e254f1 100644
--- a/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc
+++ b/doc/qtdesignstudio/src/views/qtquick-transition-editor.qdoc
@@ -25,7 +25,7 @@
 
 /*!
     \page qtquick-transition-editor.html
-    \previouspage qtquick-states-view.html
+    \previouspage studio-translations.html
     \nextpage qtquick-timeline-view.html
 
     \title Transition Editor
diff --git a/doc/qtdesignstudio/src/views/studio-translations.qdoc b/doc/qtdesignstudio/src/views/studio-translations.qdoc
new file mode 100644
index 0000000000..75aaf32179
--- /dev/null
+++ b/doc/qtdesignstudio/src/views/studio-translations.qdoc
@@ -0,0 +1,232 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt Creator documentation.
+**
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+**
+****************************************************************************/
+
+/*!
+    \page studio-translations.html
+    \previouspage qtquick-states-view.html
+    \nextpage qtquick-timeline-view.html
+
+    \title Translations
+
+    You handle translations and multi-language support in the
+    \uicontrol {Translations} view.
+
+    \image studio-translations-view.png "Translations view"
+
+    \section1 Summary of Translations View Buttons
+
+    The \uicontrol {Translations} view contains the following buttons.
+
+    \table
+    \header
+        \li Button
+        \li Function
+        \li Read More
+    \row
+        \li \inlineimage icons/select-languages.png
+        \li Select which languages you want your project to support.
+        \li
+    \row
+        \li \inlineimage icons/export-json-translations.png
+        \li Export all your translations to a JSON file.
+        \li \l{Importing and Exporting Translations}
+    \row
+        \li \inlineimage icons/import-json-translations.png
+        \li Import translations from a JSON file.
+        \li \l{Importing and Exporting Translations}
+    \row
+        \li \inlineimage icons/generate-translation-files.png
+        \li Generate Qt compiled translation source files (\e{.qm})
+        and Qt translation source files (\e{.ts}).
+        \li \l{Generating Qt Translation Source Files}
+    \row
+        \li \inlineimage icons/project-translation-test.png
+        \li Run project translation test.
+        \li \l{Running the Project Translation Test}
+    \row
+        \li \inlineimage icons/qml-translation-test.png
+        \li Run QML translation test to find missing and elided translations.
+        \li \l{Running the QML Translation Test}
+    \row
+        \li \inlineimage icons/export-translations.png
+        \li Export all translations used in your project or all translations
+        currently visible in your UI.
+        \li \l{Exporting Translations in Other Ways}
+    \endtable
+
+    \section1 Importing and Exporting Translations
+
+    You can import and export translations using JSON files.
+
+    Below is an example of a JSON translation file:
+
+    \code
+    {
+        "translatables": [
+            {
+                "trId": "translation_password",
+                "translations": [
+                    {
+                        "language": "en",
+                        "translation": "Password"
+                    },
+                    {
+                        "language": "sv",
+                        "translation": "Lösenord"
+                    }
+                ]
+            }
+        ]
+    }
+    \endcode
+
+    \section2 Importing Translations
+
+    To import a JSON translation file to your \QDS project:
+    \list
+      \li In the \uicontrol Translation view in \QDS, select
+      \inlineimage icons/import-json-translations.png
+      and open the JSON file.
+    \endlist
+    Matching \c qsTrId text strings are translated. For example,
+    if you have specified the following translation ID in the JSON file:
+      \code
+      "trId": "translation_password",
+      "translations": [
+          {
+              "language": "en",
+              "translation": "Password"
+          },
+          {
+              "language": "sv",
+              "translation": "Lösenord"
+          }
+      ]
+      \endcode
+      the translation applies to all \c qsTrId strings with that translation
+      ID in your project.
+
+    \section1 Generating Qt Translation Source Files
+
+    You need to generate Qt compiled translation source files (\e{.qm})
+    and Qt translation source files (\e{.ts}) for your project to have the
+    translations working in the actual application and \uicontrol{Live Preview}.
+
+    To generate these files, select
+    \inlineimage icons/generate-translation-files.png
+    in the \uicontrol Translations view. The files are generated
+    in \e{<project-folder>/i18n}.
+
+    \section1 Running the QML Translation Test
+
+    You can run the QML language test to find missing
+    and elided translations. Running the QML language test
+    is a quick way to check the translations in the application you have open in
+    \uicontrol{Form Editor} as it highlights errors in the UI.
+
+    To run the QML translation test:
+
+    \list 1
+      \li In the \uicontrol Translations view, select
+      \inlineimage icons/qml-translation-test.png
+      .
+      \li Select the tests to run and the highlight color
+      for each test:
+        \list
+          \li \uicontrol{Show Translation Warnings} highlights missing
+          translations.
+          \li \uicontrol{Show Found Translations} highlights all translations
+          that are correct.
+          \li \uicontrol{Show Elide Warnings} highlights all translations where
+          the text is too long to fit in the text object and therefore is elided.
+        \endlist
+        \image translation-tester.png
+      \li Select \uicontrol{Run Tests}.
+    \endlist
+
+    When the test has completed, you can see the test result highlights in
+    \uicontrol{Form Editor}.
+    \image qml-translation-test-result.png
+
+    If the test finds an error, it is highlighted for all languages. For
+    example, if a translation is missing for Swedish, it is also highlighted
+    as missing when you view any other language.
+
+    Running the QML language test generates a report in JSON format. This
+    report is generated in the project root folder with the name
+    \e {translation_report_<ui-file-name>.json}.
+
+    Example of QML language test report:
+
+    \code
+    {
+        "components": [
+            {
+                "componentPath": "C:/project-directory/content/Screen01.ui.qml",
+                "errors": [
+                    {
+                        "column": 15,
+                        "errorType": "Exceeds",
+                        "line": 45
+                    },
+                    {
+                        "column": 15,
+                        "errorType": "Missing translation",
+                        "line": 59
+                    }
+                ]
+            }
+        ]
+    }
+    \endcode
+
+    The report shows the type of error as well as line and column of the
+    affected text element in the \e{ui.qml} file.
+
+    \section1 Running the Project Translation Test
+
+    You can run the project translation test on several \e{.ui.qml} files
+    at the same time. \QDS runs the same tests as during the
+    \l{Running the QML Translation Test}{QML Translation Test} and generates the
+    same test reports but does not highlight errors in the UI.
+
+    To run the project translation test, select
+    \inlineimage icons/project-translation-test.png
+    in the \uicontrol Translations view.
+
+    \section1 Exporting Translations in Other Ways
+
+    Select
+    \inlineimage icons/export-translations.png
+    in the \uicontrol Translations view, for alternative ways to
+    export translations:
+    \list
+      \li \uicontrol{Export used translations to JSON} exports
+      all translations from the translation database that are currently in use
+      in your project.
+      \li \uicontrol{Export current documents translations to JSON} exports all
+      translations from the currently open documents in your project.
+    \endlist
+*/