Doc: describe translation sources in Developer topic

Move information from the Release Manager topic and
add information about QML sources in the Qt Linguist Manual.

Change-Id: I0d2a2ea68a2e7e94895b41436d9f973d8c2cb2aa
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@digia.com>

1 files changed, 74 insertions, 34 deletions

diff --git a/src/linguist/linguist/doc/src/linguist-manual.qdoc b/src/linguist/linguist/doc/src/linguist-manual.qdoc
index 07aa0d636..3c0d4ef42 100644
--- a/src/linguist/linguist/doc/src/linguist-manual.qdoc
+++ b/src/linguist/linguist/doc/src/linguist-manual.qdoc
@@ -181,39 +181,6 @@
     For lupdate to work successfully, it must know which translation files to
     produce. The files are listed in the application's \c .pro Qt project file.
 
-    \section1 Qt Project Files
-
-    The easiest method to use lupdate and lrelease is by specifying
-    a \c .pro Qt project file. There must be an entry in the \c TRANSLATIONS
-    section of the project file for each language that is additional to
-    the native language. A typical entry looks like this:
-
-    \snippet arrowpad/arrowpad.pro 1
-
-    Using a locale within the translation file name is useful for
-    determining which language to load at runtime. This is explained
-    in the \l{linguist-programmers.html} {Developers} chapter.
-
-    An example of a complete \c .pro file with four translation source
-    files:
-
-    \snippet doc_src_linguist-manual.pro 0
-
-    If your compiler uses a different encoding for its runtime
-    system than for its source code and you want to use  non-ASCII
-    characters in string literals, you will need to set the \c
-    CODECFORSRC. For example:
-
-    \snippet doc_src_linguist-manual.pro 2
-
-    Microsoft Visual Studio 2005 .NET appears to be the only compiler
-    for which this is necessary. However, if you want to write
-    portable code, we recommend that you avoid non-ASCII characters
-    in your source files. You can still specify non-ASCII characters
-    portably using escape sequences, for example:
-
-    \snippet doc_src_linguist-manual.cpp 3
-
     \section1 Using lupdate
 
     Usage: \c {lupdate myproject.pro}
@@ -223,7 +190,10 @@
     interface files, and produces or updates \c .ts translation
     files. The files to process and the files to update can be set at
     the command line, or provided in a \c .pro file specified as an
-    command line argument. The produced translation files are given to
+    command line argument. The developer creates the .pro file, as
+    described in \l{Qt Linguist Manual: Developers}.
+
+    The produced translation files are given to
     the translator who uses \QL to read the files and insert the
     translations.
 
@@ -867,6 +837,76 @@
     with Qt, but requires a certain amount of developer intervention and
     will of course incur some runtime performance cost.
 
+    \section1 Specifying Translation Sources in Qt Project Files
+
+    To enable release managers to use lupdate and lrelease, specify
+    a \c .pro Qt project file. There must be an entry in the \c TRANSLATIONS
+    section of the project file for each language that is additional to
+    the native language. A typical entry looks like this:
+
+    \snippet arrowpad/arrowpad.pro 1
+
+    Using a locale within the translation file name is useful for
+    determining which language to load at runtime. For more information, see
+    QLocale.
+
+    The \c lupdate tool extracts user interface strings from your application.
+    It reads the application .pro file to identify which source files
+    contain text to be translated. This means your source files must be listed
+    in the \c SOURCES or \c HEADERS entry in the .pro file. If your files are
+    not listed, the text in them will not be found.
+
+    An example of a complete \c .pro file with four translation source
+    files:
+
+    \snippet doc_src_linguist-manual.pro 0
+
+    If your compiler uses a different encoding for its runtime
+    system than for its source code and you want to use  non-ASCII
+    characters in string literals, you will need to set the \c
+    CODECFORSRC. For example:
+
+    \snippet doc_src_linguist-manual.pro 2
+
+    Microsoft Visual Studio 2005 .NET appears to be the only compiler
+    for which this is necessary. However, if you want to write
+    portable code, we recommend that you avoid non-ASCII characters
+    in your source files. You can still specify non-ASCII characters
+    portably using escape sequences, for example:
+
+    \snippet doc_src_linguist-manual.cpp 3
+
+    \section2 Use a Conditional to Hide QML Source From the Compiler
+
+    The SOURCES variable is intended for C++ source files. If you list QML
+    or JavaScript source files there, the compiler tries to build them as though
+    they are C++ files. As a workaround, you can use an \c lupdate_only{...}
+    conditional statement so the \c lupdate tool sees the .qml files but the C++
+    compiler ignores them.
+
+    For example, the following .pro file snippet specifies two .qml files in
+    the application:
+
+    \code
+    lupdate_only {
+    SOURCES = main.qml \
+              MainPage.qml
+    }
+    \endcode
+
+    You can also specify the .qml source files with a wildcard match. The
+    search is not recursive so you need to specify each directory where there
+    are user interface strings in the source code:
+
+    \code
+    lupdate_only {
+    SOURCES = *.qml \
+              *.js \
+              content/*.qml \
+              content/*.js
+    }
+    \endcode
+
     \section1 Internationalizing Applications
 
     Design your application so that it can be adapted to various languages and