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

/*!
    \page multilanguage-tutorial.html
    \ingroup gstutorials

    \title Adding multi-language support to your project
    \brief Illustrates how to add support for multiple languages to your
    project.

    \image multilanguage-project.png

    The \e{Multi-language Support} tutorial illustrates how you can add
    support for multiple languages to your project. In this tutorial you
    prepare a simple login UI for multi-language support and import
    translations from a JSON file.

    You need to download the starting project for this tutorial from
    \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/Loginui2}{here}
    before you start.

    This project consists of a login page with a couple of text elements.

    Additionally, you will use a JSON translation file in this tutorial.
    Download it from \l{https://git.qt.io/public-demos/qtdesign-studio/-/tree/master/tutorial%20projects/multi-language}{here}.

    \include run-tutorial-project.qdocinc

    \section1 JSON translation file

    The JSON translation file you are using in this project has the following
    structure:

    \code
    {
    "translatables": [
        {
            "trId": "translation_password",
            "translations": [
                {
                    "language": "en",
                    "translation": "Password"
                },
                {
                    "language": "sv",
                    "translation": "Lösenord"
                }
            ]
        },
        {
            "trId": "translation_account",
            "translations": [
                {
                    "language": "en",
                    "translation": "Qt Account"
                },
                {
                    "language": "sv",
                    "translation": "Qt Konto"
                }
            ]
        },
        {
            "trId": "translation_createaccount",
            "translations": [
                {
                    "language": "en",
                    "translation": "Create Account"
                },
                {
                    "language": "sv",
                    "translation": "Skapa Konto"
                }
            ]
        },
        {
            "trId": "translation_login",
            "translations": [
                {
                    "language": "en",
                    "translation": "Log In"
                },
                {
                    "language": "sv",
                    "translation": "Logga In"
                }
            ]
        },
        {
            "trId": "translation_username",
            "translations": [
                {
                    "language": "en",
                    "translation": "Username"
                },
                {
                    "language": "sv",
                    "translation": "Användarnamn"
                }
            ]
        }
    ]
}
    \endcode

\section1 Preparing your project

    First, you need to prepare your project for translation:

    \list 1
      \li In \uicontrol{Projects}, double-click \e{Screen01.ui.qml} to open it.
      \li All text strings that you want to translate need to be of \c
      qsTrId type. In this project the text strings are of \c qsTr type, so you
      need to change their type. Go to \uicontrol View > \uicontrol Views and select
      \uicontrol Code to open the Code view. In the \uicontrol Code view, find
      all five occurrences of \c qsTr, and replace them with \c{qsTrId}. For
      example, replace:
      \code
        text: qsTr("Qt Account")
      \endcode
      with:
      \code
        text: qsTrId("Qt Account")
      \endcode
      \li Next, you need to replace the text value with the text string
      variable from the translation file for the five text strings you want
      to translate. For example, replace:
      \code
        text: qsTrId("Qt Account")
      \endcode
      with:
      \code
        text: qsTrId("translation_account")
      \endcode
    \endlist

    \section1 Importing translations

    Next, you need to import your JSON translation file:

    \list 1
      \li Go to \uicontrol View > \uicontrol Views and select \uicontrol
      Translations to open the \uicontrol Translations view. You can
      drag it to a \l {Workspaces}{workspace} to dock it.
      \li In \uicontrol Translations, select \imageselectlanguages.
      \li Select the languages that you want to support in your project.
      For this tutorial, select \uicontrol{English - American English} and
      \uicontrol{Swedish - Svenska}.
      \li Set \uicontrol{English - American English} as
      \uicontrol {Primary language} and select \uicontrol {Ok}.
      \li Select \imageimportjsontranslations and open the \e ml_translations.json
      file. Now you can see all your imported translations in the
      \uicontrol Translations view.
      \image imported-translations.png
    \endlist

    You can select language from the dropdown list on the left side of the
    \uicontrol Translations view. Translations for the selected languages will
    show in the \uicontrol Translations view as well as in the
    \uicontrol {2D} view.

    You can run translation tests, import, and export translations as described
    in \l{Translations}.

    Finally, before you can see your translations in the application or in
    \uicontrol{Live Preview}, you must generate the Qt translation source files.
    To do this, select \imagegeneratetranslationfiles in the
    \uicontrol Translations view.

    \note \QDS generates the Qt translation source files in
    \e{<project-folder>/i18n}. To make translations visible in the application,
    move or copy the i18n directory to \e{<project-folder>/Content}.
*/
