// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page studio-translations.html
    \previouspage qtquick-states-view.html
    \nextpage qtquick-timeline-view.html

    \ingroup studio-views

    \title Translations

    \brief Handle translations and multi-language support.

    The \uicontrol Translations view is included in the
    \l{https://www.qt.io/pricing}{Qt Design Studio Enterprise license}.

    You handle translations and multi-language support in the
    \uicontrol {Translations} view.

    \image studio-translations-view.png "Translations view"

    \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": "fi",
                        "translation": "Salasana"
                    }
                ]
            }
        ]
    }
    \endcode

    \section2 Importing translations

    To import a JSON translation file to your \QDS project:
    \list
      \li In the \uicontrol Translation view in \QDS, select
      \imageimportjsontranslations
      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": "fi",
              "translation": "Salasana"
          }
      ]
      \endcode
      the translation applies to all \c qsTrId strings with that translation
      ID in your project.

    \section1 Generating the Qt translation source files

    You need to generate the Qt compiled translation source files (\e{.qm})
    and the Qt translation source files (\e{.ts}) for your project to have the
    translations working in the actual application and live preview.

    To generate these files, select
    \imagegeneratetranslationfiles
    in the \uicontrol Translations view. The files are generated
    in \e{<project-folder>/i18n}. To make translations visible in the
    application, move or copy the i18n directory to \e{<project-folder>/Content}.

    \section1 Running a translation test for a single document

    You can run the translation test to find missing translations
    and translations where the text exceeds the text element boundaries. Running
    the test is a quick way to check the translations in the document you have
    open in the \uicontrol {2D} view as it highlights errors in the UI.

    To run the test for the currently open document:

    \list 1
      \li In the \uicontrol Translations view, select
      \imageqmltranslationtest
      .
      \li Select the tests to run and the highlight color
      for each test:
        \list
          \li \uicontrol{Success} highlights translations without any warnings.
          \li \uicontrol{Missing translation} highlights translations that are
          missing for one or more languages.
          \li \uicontrol{Exceeds boundaries} highlights translations where
          the text is too long to fit in the text object.
        \endlist
        \image {translation-tester.png} {The Translation Tester dialog with all highlights selected.}
      \li Select \uicontrol{Run Tests}.
    \endlist

    When the test has completed, you can see the test result highlights in
    the \uicontrol {2D} view.
    \image {qml-translation-test-result.png} {The Test Results dialog.}

    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 a translation test for several documents

    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 a translation test for a single document}{Translation Test} and
    generates the same test reports but does not highlight errors in the UI.

    To run the translation test for several documents:
    \list 1
      \li Select
      \imageprojecttranslationtest
      in the \uicontrol Translations view.
      \li Select the files that you want to include in the test.
      \li Select \uicontrol{Run Tests}.
    \endlist

    \section1 Exporting translations in other ways

    Select
    \imageexporttranslations
    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
*/
