Build extensions with VS Code and CMake with translation

This document describe how to integrate translations in the CMake project. 

First follow the instructions on the page Build with VS Code and CMake to set up your development environment and the CMake project.
Read also the page Extension's translation where we describe how to translate extensions. 

You find a working complete example with the code on this page on our GitHub Repository at:  Full project template.

Set up development environment

To build the translations we need the lpdate and lrelease utiltiy and therefore you need to install Qt and a third CMake extension.

Install Qt

Download and install Qt from https://www.qt.io. You need to install at least one Qt Version: Qt 6.4.3, 6.5.2, 6.60, ... it doesn't matter which one, if you are unsure install the latest one.

NB.: to download and install Qt you need to have or create a free qt.io account.

Set paths to lpudate and lrelease

Add the  options BAN_QT_LUPDATE and BAN_QT_LRELEASE to the file .vscode/settings.json.

• BAN_QT_LUPDATE: path to the Qt lupdate tool. The lupdate tool is used to update the translations, it will search for text to translate in the code and update the content of *.ts files. If you don't have translations, this options is not necessary.
• BAN_QT_RELEASE: path to the Qt lrealease tool. The lrelease tool is used to compile the translations, the compiled translation are integrated in the package.If you don't have translations, this options is not necessary.

{
   "cmake.configureSettings": {
       "BAN_QT_RCC": C:/Programms/BananaPlusDev/rcc.exe",
       "BAN_EXE_PATH": "C:/Programms/BananaPlusDev/BananaPlusDev.exe",
       "BAN_QT_LUPDATE": "C:/Qt/6.5.2/macos/bin/lupdate",
       "BAN_QT_LRELEASE": "C:/Qt/6.5.2/macos/bin/lrelease"
   }
}

Set editor for *.ts files

Install the following CMake extension:

• fabiospampinato.vscode-open-in-application: Open in application extension

The installation of this extension is reccomended but not necessary. This extension let you open a file from VS Code in your preferred application, we use it to open *.ts in Qt Linguist.

Open vscode user setting file and add the editor for *.ts files

   "openInApplication.applications": {
       "*.ts": "QtLinguist"
   }

In the operating system assign the *.ts to QtLinquist application.

To open a *.ts file with QtLinguist right click on the file in the file explorer panel and select Open in Application.

Update folder structure and CMake project file

Folder structure

Add a folder /translations where the translations files .ts and *qm reside.

You don't need to create the files .ts and .qm, they are generated automatically.

/
 
  CMakeList.txt                              CMake project file

  <extension_id>.js                          Extension's code
  <extension_id>.lib.js                      
  <extension_id>.manifest.json               Metadata such title, description and version
  <extension_id>.qrc                         List of files included in the package
  <extension_id>.sbaa                        Buided package
  changelog.md                               Change history
     
  /translations
     translation_de.ts
     translation_qm.ts
        
  ...   

CMake file

Add the targets lrelease and lupdate to update and compile translations.

cmake_minimum_required(VERSION 3.16)

project(fullproject)
set(EXTENSION_ID "ch.banana.sample.fullproject")

# CMake options
# Create a file .vscode/settings.json with the following content to set the options, 
# adapt the path to your environment
# {
#     "cmake.configureSettings": {
#         "BAN_QT_RCC": "C:\users\user_name\AppData\Local\Programs\BananaPlusDev\rcc.exe",
#         "BAN_EXE_PATH": "C:\users\user_name\AppData\Local\Programs\BananaPlusDev\BananaPlusDev.exe",
#         "BAN_QT_LUPDATE": "C:\Qt\6.5.2\macos\bin\lupdate",
#         "BAN_QT_LRELEASE": "C:\Qt\6.5.2\macos\bin\lrelease"
#     }
# }
set(BAN_QT_RCC $ENV{BAN_QT_RCC} CACHE FILEPATH "Path to Qt rcc executable")
set(BAN_EXE_PATH $ENV{BAN_EXE_PATH} CACHE FILEPATH "Path to BananaPlus executable, used to run tests")
set(BAN_QT_LUPDATE $ENV{BAN_QT_LUPDATE} CACHE FILEPATH "Path to Qt lupdate executable")
set(BAN_QT_LRELEASE $ENV{BAN_QT_LRELEASE} CACHE FILEPATH "Path to Qt lrelease executable")

# This target is used to build the extension to a sbaa package
add_custom_target(${PROJECT_NAME}
    COMMAND ${BAN_QT_RCC} -o ${EXTENSION_ID}.sbaa --binary ${EXTENSION_ID}.qrc
    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
    SOURCES ${EXTENSION_ID}.qrc
)

# This target is used to run the tests of the extension
add_custom_target(test
    COMMAND ${BAN_EXE_PATH} -cmd=runtestsapps -cmd_exit=1 -cmd_p1=${CMAKE_SOURCE_DIR}/${EXTENSION_ID}.sbaa -cmd_op=A
    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
)

# The variable translations_files contains the list of translations files
set(translations_files
    translations/translations_de.ts
    translations/translations_it.ts
    translations/translations_fr.ts
)

# The target lupdate is used to update *.ts translations files
set(lupdate_commands)
foreach(tr_file ${translations_files})
  list(APPEND lupdate_commands
    COMMAND ${BAN_QT_LUPDATE} ${EXTENSION_ID}.qrc -ts ${tr_file})
endforeach()

add_custom_target(lupdate
    ${lupdate_commands}
    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
)

# The target lrelease is used to compile *.ts files to *.qm files
set(lrelease_commands)
set(lrelease_files)
string(REPLACE ".ts" "" lrelease_files "${translations_files}") #remove file extension
foreach(tr_file ${lrelease_files})
  list(APPEND lrelease_commands
      COMMAND ${BAN_QT_LRELEASE} ${tr_file}.ts -qm ${tr_file}.qm)
endforeach()

add_custom_target(lrelease
    ${lrelease_commands}
    WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
)

add_dependencies(${PROJECT_NAME} lrelease) #build .qm files when building the sbaa package

QRC file

In the qrc file insert the translations files:

<!DOCTYPE RCC><RCC version="1.0">
<qresource prefix="/">
<file>ch.banana.sample.fullproject.js</file>
<file>ch.banana.sample.fullproject.lib.js</file>
<file>manifest.json</file>
<file>translations/translations_de.qm</file>
<file>translations/translations_fr.qm</file>
<file>translations/translations_it.qm</file>
</qresource>
</RCC>

Update translations

1. Select CMake from the Activity bar (on the left)
2. Right click on the lupdate project and select Run utility
   This will update the translastions/translation_xx.ts files with the latest code changes
   
3. Open the files translastions/translation_xx.ts with Qt Linguist
   Update the translations and save the file
4. Build the extension 
   The new translations are automatically compiled and inserted in the .sbaa package