### Install Ubuntu 22.04 Dependencies (Qt6)

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Installs libraries for translateLocally on Ubuntu 22.04, utilizing Qt6. Requires sudo privileges.

```bash
sudo apt-get install -y libxkbcommon-x11-dev libpcre++-dev libvulkan-dev libgl1-mesa-dev \
    qt6-base-dev qt6-base-dev-tools qt6-tools-dev qt6-tools-dev-tools \
    qt6-l10n-tools qt6-translations-l10n libqt6svg6-dev libarchive-dev libpcre2-dev
```

--------------------------------

### Install Ubuntu 20.04 Build Dependencies

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Installs necessary development packages for compiling translateLocally on Ubuntu 20.04, including PCRE++, Qt5, libarchive, and others.

```bash
sudo apt-get install -y libpcre++-dev qttools5-dev qtbase5-dev libqt5svg5-dev libarchive-dev libpcre2-dev
```

--------------------------------

### Install Intel MKL on Ubuntu

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Installs Intel Math Kernel Library (MKL) for optimized performance on Ubuntu. This involves adding a new repository and installing the specific version.

```bash
wget -qO- "https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2019.PUB" | sudo apt-key add -

```

```bash
sudo sh -c "echo deb https://apt.repos.intel.com/mkl all main > /etc/apt/sources.list.d/intel-mkl.list"

```

```bash
sudo apt-get update -o Dir::Etc::sourcelist="/etc/apt/sources.list.d/intel-mkl.list"

```

```bash
sudo apt-get install -y --no-install-recommends intel-mkl-64bit-2020.0-088
```

--------------------------------

### Install Ubuntu 22.04 Build Dependencies

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Installs required development packages for translateLocally on Ubuntu 22.04, focusing on Qt6 and Vulkan support.

```bash
sudo apt-get install -y libxkbcommon-x11-dev libpcre++-dev libvulkan-dev libgl1-mesa-dev qt6-base-dev qt6-base-dev-tools qt6-tools-dev qt6-tools-dev-tools qt6-l10n-tools qt6-translations-l10n libqt6svg6-dev libarchive-dev libpcre2-dev
```

--------------------------------

### Install Intel MKL for Ubuntu

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Adds the Intel MKL repository and installs the 64-bit 2020.0-088 version of the MKL library for Ubuntu systems.

```bash
wget -qO- "https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2019.PUB" | sudo apt-key add -
  sudo sh -c "echo deb https://apt.repos.intel.com/mkl all main > /etc/apt/sources.list.d/intel-mkl.list"
  sudo apt-get update -o Dir::Etc::sourcelist="/etc/apt/sources.list.d/intel-mkl.list"
  sudo apt-get install -y --no-install-recommends intel-mkl-64bit-2020.0-088
```

--------------------------------

### List Installed Models

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Use the -l or --list-models option to see all locally installed translation models.

```bash
./translateLocally -l
```

--------------------------------

### Install Archlinux Dependencies

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Installs required packages for translateLocally on Arch Linux using pacman.

```bash
pacman -S libarchive pcre2 protobuf qt6-base qt6-svg intel-oneapi-mkl
```

--------------------------------

### Compile translateLocally from Source

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Standard build process using CMake. Ensure you have QT>=5 and intel-mkl-static installed. The fix_ruy_build.sh script is only needed for ARM architectures.

```bash
mkdir build
cd build
cmake ..
# this step is only necessary when compiling on ARM
# cmake should give you the absolute path of the command that needs to run:
# $GITHUB_WORKSPACE/cmake/fix_ruy_build.sh $GITHUB_WORKSPACE ${{github.workspace}}/build`
make -j5
./translateLocally
```

--------------------------------

### List Available Models for Download

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Connect to the internet and list available models using the -a or --available-models option. This shows models not installed locally or those with available updates.

```bash
./translateLocally -a
```

--------------------------------

### Install Rules for UNIX Systems

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Configures installation targets for runtime executables, desktop entries, and icons on UNIX-like systems (Linux and macOS). Includes specific logic for Debian-based systems to generate .deb packages.

```cmake
if(UNIX)  # Add Linux and apple support for make install
  include(GNUInstallDirs)
  install(
          TARGETS translateLocally-bin
          RUNTIME
         )
  install(FILES ${CMAKE_SOURCE_DIR}/dist/translateLocally.desktop DESTINATION share/applications)
  install(FILES ${CMAKE_SOURCE_DIR}/logo/translateLocally_logo.png DESTINATION share/icons)
  install(FILES ${CMAKE_SOURCE_DIR}/logo/translateLocally_logo.svg DESTINATION share/icons)

    if(NOT APPLE)
        ## Support CPACK package generation on debian like systems
        # this is triggered by running cpack after make to generate a .deb
        # This won't work on apple and would need to be modified for rpm based distros
        # Find ubuntu version
        execute_process (
            COMMAND bash -c "grep ^NAME /etc/os-release  | tr -d \"\" | tr -d \"NAME=\""
            OUTPUT_VARIABLE OS_NAME
            OUTPUT_STRIP_TRAILING_WHITESPACE
            )
        execute_process (
            COMMAND bash -c "grep VERSION_ID= /etc/os-release | tr -d \"\" | tr -d \"VERSION_ID=\""
            OUTPUT_VARIABLE OS_VERSION
            OUTPUT_STRIP_TRAILING_WHITESPACE
            )
        if(NOT DEFINED CPU_FEATURE) # Only set this in case we don't set BUILD_ARCH explicitly
            execute_process (
                COMMAND ${CMAKE_SOURCE_DIR}/dist/cpu_feature.sh
                OUTPUT_VARIABLE CPU_FEATURE
                OUTPUT_STRIP_TRAILING_WHITESPACE
                )
        endif(NOT DEFINED CPU_FEATURE)

        set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
        set(CPACK_PACKAGE_CONTACT "Nikolay Bogoychev <nheart@gmail.com>")
        set(CPACK_PACKAGE_DIRECTORY ${CMAKE_BINARY_DIR}/deb)
        set(CPACK_GENERATOR "DEB")
        set(CPACK_PACKAGE_NAME ${PROJECT_NAME})
        set(CPACK_PACKAGE_FILE_NAME ${PROJECT_NAME}-${PROJECT_VERSION_STRING_FULL}-${OS_NAME}-${OS_VERSION}.${CPU_FEATURE})
        set(CPACK_DEBIAN_PACKAGE_NAME ${PROJECT_NAME})
        set(CPACK_DEBIAN_PACKAGE_VERSION ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH})
        set(CPACK_DEBIAN_PACKAGE_DESCRIPTION "A fast privacy focused machine translation client that translates on your own machine.")

        include(CPack)
        #
        #
        ##
    endif(NOT APPLE)
endif(UNIX)
```

--------------------------------

### Example Script for Efficient Model Conversion

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

This script demonstrates converting a Marian model to its most efficient 8-bit representation, often found in the Bergamot project's GitHub repository.

```bash
Example script that converts a marian model to the most efficient 8-bit representation can also be found at Bergamot's [Github](https://github.com/browsermt/students/blob/master/esen/esen.student.tiny11/speed.cpu.intgemm8bitalpha.sh). Student models are typically at least 8X faster than teacher models such as the transformer-base preset.
```

--------------------------------

### Build translateLocally from Source

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Compile translateLocally using CMake. Ensure Qt5/Qt6, libarchive, and Intel MKL (or Apple Accelerate on macOS) are installed.

```bash
# Compile translateLocally from source with CMake. The build requires Qt5/Qt6, libarchive, and Intel MKL (or Apple Accelerate on macOS).

```

--------------------------------

### Repository JSON Format Example

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Example structure for a custom model repository JSON file. This defines metadata for translation models.

```json
{
  "models": [
    {
      "shortName": "en-de-tiny",
      "modelName": "English-German tiny",
      "src": "English",
      "trg": "German",
      "type": "tiny",
      "url": "https://example.com/models/en-de-tiny.tar.gz",
      "version": 1,
      "API": 1,
      "srcTags": {"en": "English"},
      "trgTag": "de",
      "checksum": "abc123..."
    }
  ]
}
```

--------------------------------

### Install Arch Linux Build Dependencies

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Installs packages required for building translateLocally on Arch Linux, including libarchive, pcre2, protobuf, Qt6, and Intel MKL.

```bash
# pacman -S libarchive pcre2 protobuf qt6-base qt6-svg intel-oneapi-mkl
```

--------------------------------

### Build translateLocally (macOS with Apple Accelerate)

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Builds translateLocally on macOS, utilizing Apple's Accelerate framework instead of Intel MKL. Also builds a DMG installer.

```bash
mkdir build && cd build
cmake ..
cmake --build . -j3 --target translateLocally-bin translateLocally.dmg
```

--------------------------------

### List Installed Translation Models

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

The -l flag lists all translation models currently installed on your local machine, including their type, version, and invocation command.

```bash
# List locally installed translation models
./translateLocally -l
# Output:
# Czech-English type: tiny version: 1; To invoke do -m cs-en-tiny
# German-English type: tiny version: 2; To invoke do -m de-en-tiny
# English-German type: tiny version: 2; To invoke do -m en-de-tiny
```

--------------------------------

### Apple Specific Installation and Bundling

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Configures the project for macOS, setting bundle properties for the application and linking necessary libraries. It also prepares for creating a signed and notarized .dmg file.

```cmake
if(APPLE) # Apple specific installation of the app
  # Add the .app Target
  target_link_libraries(translateLocally PRIVATE ${LINK_LIBRARIES})
  set_target_properties(translateLocally PROPERTIES
    BUNDLE True
    MACOSX_BUNDLE_BUNDLE_NAME ${CMAKE_PROJECT_NAME}
    MACOSX_BUNDLE_BUNDLE_VERSION ${PROJECT_VERSION_STRING_FULL}
    MACOSX_BUNDLE_SHORT_VERSION_STRING ${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}
    MACOSX_BUNDLE_GUI_IDENTIFIER "com.translatelocally.translateLocally"
    )
  # When on MacOS, we have a non-standard libarchive location because we get it via brew
  target_include_directories(translateLocally-bin PRIVATE ${LibArchive_INCLUDE_DIR})
  target_include_directories(translateLocally PRIVATE ${LibArchive_INCLUDE_DIR})
  # produce .dmg This requires custom target due to https://gitlab.kitware.com/cmake/cmake/-/issues/16270
  # use dist/macdmg.sh to sign and notarize
  include(macdeployqt)
  macdeployqt(translateLocally)
endif(APPLE)
```

--------------------------------

### Build translateLocally (Linux/macOS)

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Builds the translateLocally application using CMake and Make. Assumes dependencies are already installed.

```bash
mkdir build && cd build
cmake ..
make -j5
./translateLocally
```

--------------------------------

### List Models Request (Local Only)

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Request a list of locally available translation models by setting 'includeRemote' to false. This is useful for checking installed models without considering downloadable ones.

```json
{
  "id": 1,
  "command": "ListModels",
  "data": {
    "includeRemote": false
  }
}
```

--------------------------------

### Remove a Model

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Remove a locally installed model using the -r or --remove-model option, followed by the model identifier.

```bash
./translateLocally -r en-et-tiny
```

--------------------------------

### Pivot Translation via Piping

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Chain multiple translation models together using pipes to translate between language pairs without a direct model. For example, Spanish to German via English.

```bash
# Spanish -> English -> German pivot translation
cat /tmp/spanish_text.txt | ./translateLocally -m es-en-tiny | ./translateLocally -m en-de-tiny -o /tmp/german_output.txt
```

```bash
# Full example with test data
sacrebleu -t wmt13 -l en-es --echo ref > /tmp/es.in
cat /tmp/es.in | ./translateLocally -m es-en-tiny | ./translateLocally -m en-de-tiny -o /tmp/de.out
```

```bash
# Chain three models for complex language routes
echo "Bonjour le monde" | ./translateLocally -m fr-en-tiny | ./translateLocally -m en-de-tiny
# Output: Hallo Welt
```

--------------------------------

### Display Help and Options

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Use the --help flag to display all available commands and options for the translateLocally CLI.

```bash
# Display help and available options
./translateLocally --help
```

--------------------------------

### Display Help Information

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Use the --help option to display command-line options and usage instructions for translateLocally.

```bash
./translateLocally --help
```

--------------------------------

### List Available Models for Download

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Use the -a flag to see a list of translation models available for download from the server. This requires an active internet connection.

```bash
# List available models for download (requires internet)
./translateLocally -a
# Output:
# Czech-English type: base version: 1; To download do -d cs-en-base
# German-English type: base version: 2; To download do -d de-en-base
```

--------------------------------

### Build Debian/Ubuntu Package with cpack

Source: https://github.com/xapajiamnu/translatelocally/blob/master/dist/README.md

Use this command sequence to build a .deb package for Ubuntu/Debian systems. Ensure you are in the project's root directory.

```bash
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr
make -j2
cpack
```

--------------------------------

### Build from Source

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Instructions for compiling translateLocally from source using CMake.

```APIDOC
## Build from Source

Compile translateLocally from source with CMake. The build requires Qt5/Qt6, libarchive, and Intel MKL (or Apple Accelerate on macOS).

### Prerequisites:
- CMake
- Qt5 or Qt6
- libarchive
- Intel MKL (Linux/Windows) or Apple Accelerate framework (macOS)

### Build Steps:
```bash
# Create a build directory
mkdir build
cd build

# Configure the build with CMake
cmake ..

# Compile the project
cmake --build .
```
```

--------------------------------

### Create Qt Executable for Windows (Pre-Qt 6)

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Defines the main executable target for Windows when using Qt versions prior to 6. It includes the Windows icon resource.

```cmake
add_executable(translateLocally-bin
              ${PROJECT_SOURCES}
              ${APP_ICON_RESOURCE_WINDOWS}
        )
```

--------------------------------

### Build Portable Executable on MacOS

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Compiles translateLocally and creates a portable executable and a .dmg disk image on macOS using Qt's distribution. Relies on Apple's Accelerate framework instead of MKL.

```bash
mkdir build
cd build
cmake ..
cmake --build . -j3 --target translateLocally-bin translateLocally.dmg
```

--------------------------------

### Enter Nix Flake Development Shell

Source: https://github.com/xapajiamnu/translatelocally/blob/master/dist/README.md

Enter the development shell provided by the Nix Flake. Development dependencies will be available until the shell is exited.

```bash
nix develop
```

--------------------------------

### Create Signed and Notarized DMG on MacOS

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Builds translateLocally and then uses the provided macdmg.sh script to create a signed and notarized .dmg file for distribution on macOS. Requires environment variables to be set for signing.

```bash
mkdir build
cd build
cmake ..
make -j5
../dist/macdmg.sh .
```

--------------------------------

### Create Qt Executable for macOS (Pre-Qt 6)

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Defines the main executable target for macOS when using Qt versions prior to 6. It includes application bundle settings and specifies icon and entitlement files.

```cmake
add_executable(translateLocally MACOSX_BUNDLE
              ${PROJECT_SOURCES}
              ${APP_ICON_MACOSX}
              ${APP_ENTITLEMENTS_MACOSX}
          )
```

--------------------------------

### Create Qt Executable for Windows (Qt 6+)

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Defines the main executable target for Windows when using Qt 6 or later. It includes the Windows icon resource.

```cmake
qt_add_executable(translateLocally-bin
   ${PROJECT_SOURCES}
   ${APP_ICON_RESOURCE_WINDOWS}
)
```

--------------------------------

### Build translateLocally with OpenBLAS

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Builds translateLocally using OpenBLAS. Performance may be slower than MKL. Disables OpenMP for potentially better performance.

```bash
mkdir build && cd build
cmake .. -DBLAS_LIBRARIES=-lblas -DCBLAS_LIBRARIES=-lcblas
make -j6
OMP_NUM_THREADS=1 ./translateLocally
```

--------------------------------

### Build with OpenBLAS on Linux

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Builds translateLocally using OpenBLAS as the BLAS provider. It's strongly discouraged due to performance issues compared to MKL. Disables OpenMP for better performance with small matrices.

```bash
mkdir build
cd build
cmake .. -DBLAS_LIBRARIES=-lblas -DCBLAS_LIBRARIES=-lcblas
make -j6
OMP_NUM_THREADS=1 ./translateLocally # disable OpenMP parallelization.
```

--------------------------------

### Create Qt Executable for macOS (Qt 6+)

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Defines the main executable target for macOS when using Qt 6 or later. It includes application bundle settings and specifies icon and entitlement files.

```cmake
if(${QT_VERSION_MAJOR} GREATER_EQUAL 6)
   if(APPLE)
     qt_add_executable(translateLocally MACOSX_BUNDLE
       ${PROJECT_SOURCES}
       ${APP_ICON_MACOSX}
       ${APP_ENTITLEMENTS_MACOSX}
     )
   endif()

    qt_add_executable(translateLocally-bin
       ${PROJECT_SOURCES}
       ${APP_ICON_RESOURCE_WINDOWS}
    )

    qt_create_translation(QM_FILES ${CMAKE_SOURCE_DIR} ${TS_FILES})
else()
    if(ANDROID)
        add_library(translateLocally-bin SHARED
            ${PROJECT_SOURCES}
        )
    else()
        if(APPLE)
          add_executable(translateLocally MACOSX_BUNDLE
              ${PROJECT_SOURCES}
              ${APP_ICON_MACOSX}
              ${APP_ENTITLEMENTS_MACOSX}
          )
        endif()
        add_executable(translateLocally-bin
              ${PROJECT_SOURCES}
              ${APP_ICON_RESOURCE_WINDOWS}
        )
    endif()

    qt5_create_translation(QM_FILES ${CMAKE_SOURCE_DIR} ${TS_FILES})
endif()
```

--------------------------------

### Define Link Libraries

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Lists the libraries to be linked against the main executable. This includes Qt modules, project-specific libraries, and system libraries.

```cmake
set(LINK_LIBRARIES
    Qt${QT_VERSION_MAJOR}::Core
    Qt${QT_VERSION_MAJOR}::Gui
    Qt${QT_VERSION_MAJOR}::PrintSupport
    Qt${QT_VERSION_MAJOR}::Widgets
    Qt${QT_VERSION_MAJOR}::Network
    Qt${QT_VERSION_MAJOR}::DBus
    Qt${QT_VERSION_MAJOR}::Svg
    bergamot-translator
    ${CMAKE_THREAD_LIBS_INIT} # This should work on all platforms?
    ${LibArchive_LIBRARIES}
    ${CMAKE_DL_LIBS}) # On unix necessary sometimes
```

--------------------------------

### Create Qt Executable for Android (Pre-Qt 6)

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Defines a shared library target for Android builds when using Qt versions prior to 6. This is used for building the Android application.

```cmake
add_library(translateLocally-bin SHARED
            ${PROJECT_SOURCES}
        )
```

--------------------------------

### Archive Custom Model for Import

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

After organizing your model files, create a tar.gz archive for easy import into translateLocally.

```bash
tar -czvf my-custom-model.tar.gz my-custom-model
```

--------------------------------

### Set Icon File for Windows and macOS

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Configures the application icon resource for Windows and macOS builds. This is typically done at the beginning of the CMakeLists.txt file.

```cmake
if(WIN32)
    set(APP_ICON_RESOURCE_WINDOWS "${CMAKE_CURRENT_SOURCE_DIR}/logo/translateLocally.rc")
elseif(APPLE)
    set(MACOSX_BUNDLE_ICON_FILE "translateLocally.icns")
    set(APP_ICON_MACOSX ${CMAKE_CURRENT_SOURCE_DIR}/logo/translateLocally.icns)
    set(APP_ENTITLEMENTS_MACOSX ${CMAKE_CURRENT_SOURCE_DIR}/dist/translateLocally.entitlements)
    set_source_files_properties(${APP_ICON_MACOSX} PROPERTIES MACOSX_PACKAGE_LOCATION "Resources")
    set_source_files_properties(${APP_ENTITLEMENTS_MACOSX} PROPERTIES MACOSX_PACKAGE_LOCATION "Resources")
endif(WIN32)
```

--------------------------------

### Download a Model

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Download a specific translation model from the internet using the -d or --download-model option, followed by the model identifier.

```bash
./translateLocally -d en-et-tiny
```

--------------------------------

### Include Build Directory

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Adds the current binary directory to the include paths. This is necessary to find generated header files like 'version.h'.

```cmake
include_directories(${CMAKE_CURRENT_BINARY_DIR})
```

--------------------------------

### Configure Project Version

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Generates a version header file ('version.h') based on a template ('version.h.in'). This makes project version information available to the C++ code.

```cmake
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/version.h.in
               ${CMAKE_CURRENT_BINARY_DIR}/version.h @ONLY)
```

--------------------------------

### Quantize Model using marian-conv

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Use the marian-conv tool from the Bergamot fork to quantize your model to 8-bit integers for improved efficiency. Ensure the MARIAN environment variable is set correctly.

```bash
$MARIAN/marian-conv -f input_model.npz -t output_model.bin --gemm-type intgemm8
```

--------------------------------

### Set Build Options

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Configures various build options for the project, such as enabling or disabling CUDA compilation, SentencePiece integration, static library linking, and WASM compatibility.

```cmake
SET(COMPILE_CUDA OFF CACHE BOOL "Compile GPU version")
SET(USE_SENTENCEPIECE ON CACHE BOOL "Download and compile SentencePiece")
SET(USE_STATIC_LIBS ON CACHE BOOL "Link statically against non-system libs")
SET(USE_WASM_COMPATIBLE_SOURCE OFF CACHE BOOL "Don't build wasm compatible sources")
```

--------------------------------

### Set Project Sources

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Defines the list of source files for the project. This includes C++ source and header files, UI files, and generated header files.

```cmake
SET(PROJECT_SOURCES
        src/main.cpp
        src/mainwindow.cpp
        src/mainwindow.h
        src/mainwindow.ui
        src/AlignmentHighlighter.cpp
        src/AlignmentHighlighter.h
        src/AlignmentWorker.cpp
        src/AlignmentWorker.h
        src/ColorWell.cpp
        src/ColorWell.h
        src/FilterTableView.cpp
        src/FilterTableView.h
        src/MarianInterface.cpp
        src/MarianInterface.h
        src/Network.cpp
        src/Network.h
        src/Translation.h
        src/Translation.cpp
        src/types.h
        src/cli/CLIParsing.h
        src/cli/CommandLineIface.cpp
        src/cli/CommandLineIface.h
        src/cli/NativeMsgIface.cpp
        src/cli/NativeMsgIface.h
        src/cli/NativeMsgManager.cpp
        src/cli/NativeMsgManager.h
        src/inventory/ModelManager.cpp
        src/inventory/ModelManager.h
        src/settings/NewRepoDialog.cpp
        src/settings/NewRepoDialog.h
        src/settings/NewRepoDialog.ui
        src/settings/RepositoryTableModel.cpp
        src/settings/RepositoryTableModel.h
        src/settings/Settings.cpp
        src/settings/Settings.h
        src/settings/TranslatorSettingsDialog.cpp
        src/settings/TranslatorSettingsDialog.h
        src/settings/TranslatorSettingsDialog.ui
        logo/logo_svg.h
        ${TS_FILES}
)
```

--------------------------------

### Find Qt Package

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Finds the Qt package, specifying required components like Core, Gui, PrintSupport, Widgets, LinguistTools, Network, DBus, and Svg. It supports both Qt6 and Qt5.

```cmake
find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Gui PrintSupport Widgets LinguistTools Network DBus Svg REQUIRED)
find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core Gui PrintSupport Widgets LinguistTools Network DBus Svg REQUIRED)
```

--------------------------------

### Create Qt Translation Files (Pre-Qt 6)

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Generates QM translation files from TS source files using Qt 5 CMake functions. This is part of the overall build process for internationalization.

```cmake
qt5_create_translation(QM_FILES ${CMAKE_SOURCE_DIR} ${TS_FILES})
```

--------------------------------

### Download a Specific Translation Model

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

The -d flag allows you to download a specific translation model to your local machine. The output indicates the download progress and success.

```bash
# Download a specific model
./translateLocally -d en-de-tiny
# Output:
# Downloading English-German type: tiny...
# 100% [############################################################]
# Model downloaded successfully! You can now invoke it with -m en-de-tiny
```

--------------------------------

### Create Qt Translation Files (Qt 6+)

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Generates QM translation files from TS source files using Qt 6 CMake functions. This is part of the overall build process for internationalization.

```cmake
qt_create_translation(QM_FILES ${CMAKE_SOURCE_DIR} ${TS_FILES})
```

--------------------------------

### Custom Model Import Structure

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Define the required directory structure and file contents for importing custom translation models trained with Marian NMT. Package the model into a tar.gz archive.

```bash
# Required model directory structure
my-custom-model/
├── config.intgemm8bitalpha.yml  # Marian configuration (required filename)
├── model_info.json              # Model metadata (required filename)
├── model.npz                    # Model weights (or quantized .bin)
└── vocab.deen.spm               # SentencePiece vocabulary

# model_info.json content
{
  "modelName": "German-English tiny",
  "shortName": "de-en-tiny",
  "type": "tiny",
  "src": "German",
  "trg": "English",
  "version": 2.0,
  "API": 1.0
}

# Package the model for import
tar -czvf my-custom-model.tar.gz my-custom-model

# Import via GUI: Edit -> Translator Settings -> Languages -> Import model

# Quantize model for better performance using Bergamot's marian-conv
$MARIAN/marian-conv -f input_model.npz -t output_model.bin --gemm-type intgemm8

# Update config.intgemm8bitalpha.yml to use quantized model:
# models:
#   - output_model.bin
# gemm-precision: int8shift

```

--------------------------------

### Translate a Dataset

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Translate a dataset by providing an input file path using the -i option and specifying an output file path with the -o option. Ensure the model is selected with the -m option.

```bash
sacrebleu -t wmt13 -l en-es --echo ref > /tmp/es.in
./translateLocally -m es-en-tiny -i /tmp/es.in -o /tmp/en.out
```

--------------------------------

### Translate using macOS App with Pipes

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

For the macOS translateLocally.app version, use pipes for input and output redirection when file reading is not supported. Specify the model with -m.

```bash
translateLocally.app/Contents/MacOS/translateLocally -m es-en-tiny < input.txt > output.txt
```

--------------------------------

### List Models Request (Include Remote)

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Request a list of all available translation models, including those that can be downloaded remotely, by setting 'includeRemote' to true. This provides a comprehensive view of available models.

```json
{
  "id": 2,
  "command": "ListModels",
  "data": {
    "includeRemote": true
  }
}
```

--------------------------------

### Custom Model Import

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Instructions for creating and importing custom translation models trained with Marian NMT.

```APIDOC
## Custom Model Import

Create and import custom translation models trained with Marian NMT. Models require a specific directory structure with configuration and metadata files.

### Required Model Directory Structure:
```
my-custom-model/
├── config.intgemm8bitalpha.yml  # Marian configuration (required filename)
├── model_info.json              # Model metadata (required filename)
├── model.npz                    # Model weights (or quantized .bin)
└── vocab.deen.spm               # SentencePiece vocabulary
```

### `model_info.json` Example:
```json
{
  "modelName": "German-English tiny",
  "shortName": "de-en-tiny",
  "type": "tiny",
  "src": "German",
  "trg": "English",
  "version": 2.0,
  "API": 1.0
}
```

### Packaging the Model:
```bash
tar -czvf my-custom-model.tar.gz my-custom-model
```

### Importing the Model:
Import the packaged model via the GUI: `Edit -> Translator Settings -> Languages -> Import model`.

### Quantizing the Model (Optional):
Quantize the model for better performance using Bergamot's `marian-conv`.

```bash
$MARIAN/marian-conv -f input_model.npz -t output_model.bin --gemm-type intgemm8
```

### Updating Configuration for Quantized Model:
Modify `config.intgemm8bitalpha.yml` to use the quantized model:
```yaml
models:
  - output_model.bin
gemm-precision: int8shift
```
```

--------------------------------

### Python Async Client for translateLocally

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Use this client for concurrent translation requests via the native messaging protocol. Ensure the binary path is correct.

```python
#!/usr/bin/env python3
import asyncio
import struct
import json
import itertools
from pathlib import Path

class TranslateLocallyClient:
    """Async client for translateLocally native messaging interface."""

    def __init__(self, binary_path):
        self.binary_path = binary_path
        self.serial = itertools.count(1)
        self.futures = {}

    async def __aenter__(self):
        self.proc = await asyncio.create_subprocess_exec(
            self.binary_path, "-p",
            stdin=asyncio.subprocess.PIPE,
            stdout=asyncio.subprocess.PIPE
        )
        self.read_task = asyncio.create_task(self._reader())
        return self

    async def __aexit__(self, *args):
        self.proc.stdin.close()
        await self.proc.wait()

    def _send_request(self, command, data):
        message_id = next(self.serial)
        message = json.dumps({"command": command, "id": message_id, "data": data}).encode()
        future = asyncio.get_running_loop().create_future()
        self.futures[message_id] = future
        self.proc.stdin.write(struct.pack("@I", len(message))))
        self.proc.stdin.write(message)
        return future

    async def _reader(self):
        while True:
            try:
                raw_length = await self.proc.stdout.readexactly(4)
                length = struct.unpack("@I", raw_length)[0]
                raw_message = await self.proc.stdout.readexactly(length)
                message = json.loads(raw_message)

                if "id" in message and "success" in message:
                    future = self.futures.pop(message["id"])
                    if message["success"]:
                        future.set_result(message["data"])
                    else:
                        future.set_exception(Exception(message["error"]))
            except asyncio.IncompleteReadError:
                break

    async def list_models(self, include_remote=False):
        return await self._send_request("ListModels", {"includeRemote": include_remote})

    async def translate(self, text, src=None, trg=None, model=None, html=False):
        if src and trg:
            data = {"src": src, "trg": trg, "text": text, "html": html}
        elif model:
            data = {"model": model, "text": text, "html": html}
        else:
            raise ValueError("Must specify either src+trg or model")
        result = await self._send_request("Translate", data)
        return result["target"]["text"]

    async def download_model(self, model_id):
        return await self._send_request("DownloadModel", {"modelID": model_id})


async def main():
    async with TranslateLocallyClient("./build/translateLocally") as tl:
        # List available models
        models = await tl.list_models(include_remote=True)
        print(f"Found {len(models)} models")

        # Translate text using language codes
        result = await tl.translate("Hello world!", src="en", trg="de")
        print(f"Translation: {result}")  # Output: Hallo Welt!

        # Concurrent translations
        translations = await asyncio.gather(
            tl.translate("Good morning", src="en", trg="de"),
            tl.translate("How are you?", src="en", trg="es"),
            tl.translate("Thank you", src="en", trg="de"),
        )
        print(translations)
        # Output: ['Guten Morgen', '¿Cómo estás?', 'Danke']

asyncio.run(main())
```

--------------------------------

### ListModels Command API

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

This API allows you to list available translation models, including optionally remote models that can be downloaded. It returns detailed information about each model.

```APIDOC
## ListModels Command

### Description
Lists available translation models, optionally including remote models that can be downloaded. Returns detailed model information including language pairs, types, and availability status.

### Method
N/A (stdin/stdout messaging)

### Endpoint
N/A (stdin/stdout messaging)

### Parameters
#### Request Body
- **id** (integer) - Required - Unique identifier for the message.
- **command** (string) - Required - Must be "ListModels".
- **data** (object) - Contains parameters for listing models.
  - **includeRemote** (boolean) - Optional - If true, includes remote (downloadable) models. Defaults to false.

### Request Example
```json
{
  "id": 1,
  "command": "ListModels",
  "data": {
    "includeRemote": false
  }
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the request.
- **success** (boolean) - True if the model list was retrieved successfully.
- **data** (array) - An array of model objects.
  - **id** (string) - Unique identifier for the model.
  - **shortname** (string) - Short name of the model (e.g., "en-de-tiny").
  - **modelName** (string) - Human-readable name of the model.
  - **local** (boolean) - True if the model is installed locally.
  - **src** (string) - Source language name.
  - **trg** (string) - Target language name.
  - **srcTags** (object) - Mapping of language codes to language names for the source.
  - **trgTag** (string) - Language code for the target.
  - **type** (string) - Type of the model (e.g., "tiny", "base").
  - **repositoryUrl** (string) - URL of the model repository.

#### Response Example
```json
{
  "id": 1,
  "success": true,
  "data": [
    {
      "id": "en-de-tiny123456",
      "shortname": "en-de-tiny",
      "modelName": "English-German tiny",
      "local": true,
      "src": "English",
      "trg": "German",
      "srcTags": {
        "en": "English"
      },
      "trgTag": "de",
      "type": "tiny",
      "repositoryUrl": "https://translatelocally.com/models.json"
    }
  ]
}
```
```

--------------------------------

### Download Model Request

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Initiate the download of a translation model using its unique model ID. The 'modelID' should correspond to an available model in the remote repository.

```json
{
  "id": 1,
  "command": "DownloadModel",
  "data": {
    "modelID": "en-de-tiny123456"
  }
}
```

--------------------------------

### DownloadModel Command API

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

This API allows you to download a translation model from a remote repository. It provides progress updates during the download and returns model information upon completion.

```APIDOC
## DownloadModel Command

### Description
Downloads a translation model from a remote repository. Provides progress updates during download and returns complete model information upon success.

### Method
N/A (stdin/stdout messaging)

### Endpoint
N/A (stdin/stdout messaging)

### Parameters
#### Request Body
- **id** (integer) - Required - Unique identifier for the message.
- **command** (string) - Required - Must be "DownloadModel".
- **data** (object) - Contains parameters for downloading the model.
  - **modelID** (string) - Required - The ID of the model to download.

### Request Example
```json
{
  "id": 1,
  "command": "DownloadModel",
  "data": {
    "modelID": "en-de-tiny123456"
  }
}
```

### Response
#### Progress Update
- **id** (integer) - The ID of the request.
- **update** (boolean) - True if this is a progress update.
- **data** (object) - Contains download progress information.
  - **id** (string) - The ID of the model being downloaded.
  - **url** (string) - The URL of the model file.
  - **read** (integer) - The number of bytes downloaded so far.
  - **size** (integer) - The total size of the model file in bytes.

#### Progress Update Example
```json
{
  "id": 1,
  "update": true,
  "data": {
    "id": "en-de-tiny123456",
    "url": "https://translatelocally.com/models/en-de-tiny.tar.gz",
    "read": 5242880,
    "size": 15728640
  }
}
```

#### Success Response (200)
- **id** (integer) - The ID of the request.
- **success** (boolean) - True if the model was downloaded successfully.
- **data** (object) - Contains the information of the downloaded model.
  - **id** (string) - Unique identifier for the model.
  - **shortname** (string) - Short name of the model.
  - **modelName** (string) - Human-readable name of the model.
  - **local** (boolean) - True if the model is installed locally.
  - **src** (string) - Source language name.
  - **trg** (string) - Target language name.
  - **srcTags** (object) - Mapping of language codes to language names for the source.
  - **trgTag** (string) - Language code for the target.
  - **type** (string) - Type of the model.
  - **repositoryUrl** (string) - URL of the model repository.

#### Success Response Example
```json
{
  "id": 1,
  "success": true,
  "data": {
    "id": "en-de-tiny123456",
    "shortname": "en-de-tiny",
    "modelName": "English-German tiny",
    "local": true,
    "src": "English",
    "trg": "German",
    "srcTags": {
      "en": "English"
    },
    "trgTag": "de",
    "type": "tiny",
    "repositoryUrl": "https://translatelocally.com/models.json"
  }
}
```
```

--------------------------------

### Set Windows Executable Property

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Configures the 'translateLocally-bin' target to be a Windows GUI executable, preventing a console window from appearing on launch.

```cmake
set_property(TARGET translateLocally-bin PROPERTY WIN32_EXECUTABLE TRUE)
```

--------------------------------

### Model Directory Structure for translateLocally

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

This structure is required for translateLocally to load custom models. The config file name is hardcoded.

```bash
tree my-custom-model
my-custom-model/
├── config.intgemm8bitalpha.yml
├── model_info.json
├── model.npz
└── vocab.deen.spm
```

--------------------------------

### Download Model Progress Update

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Receive progress updates during a model download. This message includes the model ID, download URL, and the amount of data read versus the total size.

```json
{
  "id": 1,
  "update": true,
  "data": {
    "id": "en-de-tiny123456",
    "url": "https://translatelocally.com/models/en-de-tiny.tar.gz",
    "read": 5242880,
    "size": 15728640
  }
}
```

--------------------------------

### ARM Architecture Build Workaround

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Detects if the build is occurring on an ARM architecture and prints a warning message with instructions to manually fix build issues related to RUY and QT's MOC. This requires running a specific shell script.

```cmake
# Finally when using ARM we need to fix the build due to issues with RUY and QT's MOC
# First detect if we are on ARM
include(TargetArch)
target_architecture(CMAKE_TARGET_ARCHITECTURES)
list(LENGTH CMAKE_TARGET_ARCHITECTURES cmake_target_arch_len)
if(NOT "${cmake_target_arch_len}" STREQUAL "1")
    set(CMAKE_TARGET_ARCHITECTURE_UNIVERSAL TRUE)
    set(CMAKE_TARGET_ARCHITECTURE_CODE "universal")
else()
    set(CMAKE_TARGET_ARCHITECTURE_UNIVERSAL FALSE)
    set(CMAKE_TARGET_ARCHITECTURE_CODE "${CMAKE_TARGET_ARCHITECTURES}")
endif()
# Now echo the workaround
if(${CMAKE_TARGET_ARCHITECTURE_CODE} MATCHES "arm")
	message(WARNING "Building on ARM. You need to manually fix the broken build due to RUY using bad header names and QT's MOC. Please run:")
	execute_process(COMMAND echo -e "${CMAKE_SOURCE_DIR}/cmake/fix_ruy_build.sh ${CMAKE_SOURCE_DIR} ${CMAKE_BINARY_DIR}")
	message(WARNING "Before building the project")
endif()
```

--------------------------------

### Pivot Translation

Source: https://github.com/xapajiamnu/translatelocally/blob/master/README.md

Chain multiple translateLocally commands using pipes to perform pivot translations, such as Spanish to German via English.

```bash
sacrebleu -t wmt13 -l en-es --echo ref > /tmp/es.in
cat /tmp/es.in | ./translateLocally -m es-en-tiny | ./translateLocally -m en-de-tiny -o /tmp/de.out
```

--------------------------------

### Add Subdirectory

Source: https://github.com/xapajiamnu/translatelocally/blob/master/CMakeLists.txt

Includes the '3rd_party' subdirectory into the build. This is typically used to compile or link external libraries or modules.

```cmake
add_subdirectory(3rd_party)
```

--------------------------------

### Translate Single Sentence via Stdin

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

Translate individual sentences by piping text through stdin to the CLI. Specify the model using the -m flag. The translation is output to stdout by default.

```bash
# Translate Spanish to English using stdin pipe
echo "Me gustaria comprar la casa verde" | ./translateLocally -m es-en-tiny
# Output: I would like to buy the green house.
```

```bash
# Translate English to German
echo "Hello, how are you today?" | ./translateLocally -m en-de-tiny
# Output: Hallo, wie geht es Ihnen heute?
```

```bash
# Translate with explicit input text (stdin is used if -i is not specified)
echo "The weather is beautiful" | ./translateLocally -m en-es-tiny
# Output: El tiempo es hermoso
```

--------------------------------

### Python Async Client

Source: https://context7.com/xapajiamnu/translatelocally/llms.txt

The Python native client provides an asyncio-based interface for programmatic translation. It handles the native messaging protocol automatically and supports concurrent translation requests.

```APIDOC
## Python Async Client

The Python native client provides an asyncio-based interface for programmatic translation. It handles the native messaging protocol automatically and supports concurrent translation requests.

### Class: TranslateLocallyClient

#### `__init__(self, binary_path)`
Initializes the client with the path to the translateLocally binary.

#### `__aenter__(self)`
Asynchronous context manager entry point. Starts the translateLocally process and the reader task.

#### `__aexit__(self, *args)`
Asynchronous context manager exit point. Closes the stdin pipe and waits for the process to exit.

#### `_send_request(self, command, data)`
Internal method to send a request to the translateLocally process.

#### `_reader(self)`
Internal method to read responses from the translateLocally process.

#### `list_models(self, include_remote=False)`
Lists available translation models. Set `include_remote` to `True` to include remote models.

#### `translate(self, text, src=None, trg=None, model=None, html=False)`
Translates the given text. Requires either `src` and `trg` language codes or a `model` name. `html` can be set to `True` to preserve HTML tags.

#### `download_model(self, model_id)`
Downloads a specified translation model.

### Example Usage:
```python
import asyncio

async def main():
    async with TranslateLocallyClient("./build/translateLocally") as tl:
        # List available models
        models = await tl.list_models(include_remote=True)
        print(f"Found {len(models)} models")

        # Translate text using language codes
        result = await tl.translate("Hello world!", src="en", trg="de")
        print(f"Translation: {result}")

        # Concurrent translations
        translations = await asyncio.gather(
            tl.translate("Good morning", src="en", trg="de"),
            tl.translate("How are you?", src="en", trg="es"),
            tl.translate("Thank you", src="en", trg="de"),
        )
        print(translations)

asyncio.run(main())
```
```