{"id":13689819,"url":"https://github.com/XapaJIaMnu/translateLocally","last_synced_at":"2025-05-02T06:31:23.286Z","repository":{"id":39725127,"uuid":"357574796","full_name":"XapaJIaMnu/translateLocally","owner":"XapaJIaMnu","description":"Fast and secure translation on your local machine, powered by marian and Bergamot.","archived":false,"fork":false,"pushed_at":"2025-03-30T19:11:35.000Z","size":5438,"stargazers_count":539,"open_issues_count":49,"forks_count":33,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-13T23:35:34.304Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XapaJIaMnu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-13T14:04:08.000Z","updated_at":"2025-04-10T14:54:33.000Z","dependencies_parsed_at":"2024-01-13T22:24:39.540Z","dependency_job_id":"85246457-e2b4-4261-b697-8e6b3b9ae24c","html_url":"https://github.com/XapaJIaMnu/translateLocally","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XapaJIaMnu%2FtranslateLocally","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XapaJIaMnu%2FtranslateLocally/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XapaJIaMnu%2FtranslateLocally/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XapaJIaMnu%2FtranslateLocally/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XapaJIaMnu","download_url":"https://codeload.github.com/XapaJIaMnu/translateLocally/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251998413,"owners_count":21677980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T16:00:27.924Z","updated_at":"2025-05-02T06:31:23.279Z","avatar_url":"https://github.com/XapaJIaMnu.png","language":"C++","funding_links":[],"categories":["Applications 💻","C++"],"sub_categories":[],"readme":"# translateLocally\nFast and secure translation on your local machine with a GUI, powered by marian and Bergamot.\n\n## Downloads\n\nYou can download the latest automatic build for Windows, Linux and Mac from the [releases](https://github.com/XapaJIaMnu/translateLocally/releases) github tab or from the [official website](https://translatelocally.com). We also have compatibility builds for Windows and Mac that aim to cover very old hardware and M1.\n\n\n## Compile from source\nBringing fast and secure machine translation to the masses! To build and run\n```bash\nmkdir build\ncd build\ncmake ..\n# this step is only necessary when compiling on ARM\n# cmake should give you the absolute path of the command that needs to run:\n# $GITHUB_WORKSPACE/cmake/fix_ruy_build.sh $GITHUB_WORKSPACE ${{github.workspace}}/build`\nmake -j5\n./translateLocally\n```\n\nRequires `QT\u003e=5 libarchive intel-mkl-static`. We make use of the `QT\u003e=5 network`, `QT\u003e=5 linguisticTool` and `QT\u003e=5 svg` components. Depending on your distro, those may be split in separate package from your QT package (Eg `qt{6/7}-tools-dev`; `qt{5/6}-svg` or `libqt5svg5-dev`). QT6 is fully supported and its use is encouraged. `intel-mkl-static` may be part of `mkl` or `intel-mkl` packages.\n\n### Ubuntu 20.04 build dependencies:\n```bash\nsudo apt-get install -y libpcre++-dev qttools5-dev qtbase5-dev libqt5svg5-dev libarchive-dev libpcre2-dev\n```\n\n### Ubuntu 22.04 build dependencies:\n```bash\nsudo 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\n```\n#### Install MKL for Ubuntu (Any)\n```bash\nwget -qO- \"https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS-2019.PUB\" | sudo apt-key add -\n  sudo sh -c \"echo deb https://apt.repos.intel.com/mkl all main \u003e /etc/apt/sources.list.d/intel-mkl.list\"\n  sudo apt-get update -o Dir::Etc::sourcelist=\"/etc/apt/sources.list.d/intel-mkl.list\"\n  sudo apt-get install -y --no-install-recommends intel-mkl-64bit-2020.0-088\n```\n\n### Archlinux build dependencies\n```\n# pacman -S libarchive pcre2 protobuf qt6-base qt6-svg intel-oneapi-mkl\n```\n\n### OpenBlas\nWe technically support building against OpenBLAS as a BLAS provider, but we **strongly discourage it**. The performance offered by OpenBLAS is significantly lower than that of Intel's MKL, regardless of the CPU manufacturer. Furthermore, OpenBLAS enables OpenMP parallelization by default, but unfortunately our matrices are too small to take advantage of OpenMP and we end up with up to 100x slowdown compared MKL in the worst case scenario with the majority of end users not aware of how to debug this issue. How sad. \n\nIf you *really* want to use OpenBLAS instead you can do:\n```bash\nmkdir build\ncd build\ncmake .. -DBLAS_LIBRARIES=-lblas -DCBLAS_LIBRARIES=-lcblas\nmake -j6\nOMP_NUM_THREADS=1 ./translateLocally # disable OpenMP parallelization.\n```\n\n## MacOS Build\nOn MacOS, translateLocally doesn't rely on MKL, but instead on Apple accelerate. If you want to build a portable executable that is able to run on multiple machines, we recommend using Qt's distribution of Qt, as opposed to homebrew's due to issues with [macdeployqt](https://github.com/XapaJIaMnu/translateLocally/issues/69). To produce a `.dmg`do:\n```bash\nmkdir build\ncd build\ncmake ..\ncmake --build . -j3 --target translateLocally-bin translateLocally.dmg\n```\nAlternatively, if you wish to sign and notarize the `.dmg`for distribution, you may use [macdmg.sh](dist/macdmg.sh)\n```bash\nmkdir build\ncd build\ncmake ..\nmake -j5\n../dist/macdmg.sh .\n```\nCheck the script for the environment variables that you need to set if you want to take advantage of signing and notarization.\n\n## Windows Build\nOn Windows, we recommend using [vcpkg](https://github.com/Microsoft/vcpkg) to install all necessary packages and Visual Studio to perform the build.\n\n# Command line interface\ntranslateLocally supports using the command line to perform translations. Example usage:\n```bash\n./translateLocally --help\nUsage: ./translateLocally [options]\nA secure translation service that performs translations for you locally, on your own machine.\n\nOptions:\n  -h, --help                     Displays help on commandline options.\n  --help-all                     Displays help including Qt specific options.\n  -v, --version                  Displays version information.\n  -l, --list-models              List locally installed models.\n  -a, --available-models         Connect to the Internet and list available\n                                 models. Only shows models that are NOT\n                                 installed locally or have a new version\n                                 available online.\n  -d, --download-model \u003coutput\u003e  Connect to the Internet and download a model.\n  -r, --remove-model \u003coutput\u003e    Remove a model from the local machine. Only\n                                 works for models managed with translateLocally.\n  -m, --model \u003cmodel\u003e            Select model for translation.\n  -i, --input \u003cinput\u003e            Source translation text (or just used stdin).\n  -o, --output \u003coutput\u003e          Target translation output (or just used\n                                 stdout).\n```\n\n## Downloading models from CLI\nModels can be downloaded from the GUI or the CLI. For the CLI model management you need to:\n```bash\n$ ./translateLocally -a\nCzech-English type: base version: 1; To download do -d cs-en-base\nGerman-English type: base version: 2; To download do -d de-en-base\nEnglish-Czech type: base version: 1; To download do -d en-cs-base\nEnglish-German type: base version: 2; To download do -d en-de-base\nEnglish-Estonian type: tiny version: 1; To download do -d en-et-tiny\nEstonian-English type: tiny version: 1; To download do -d et-en-tiny\nIcelandic-English type: tiny version: 1; To download do -d is-en-tiny\nNorwegian (Bokmal)-English type: tiny version: 1; To download do -d nb-en-tiny\nNorwegian (Nynorsk)-English type: tiny version: 1; To download do -d nn-en-tiny\n\n$ ./translateLocally -d en-et-tiny\nDownloading English-Estonian type: tiny...\n100% [############################################################]\nModel downloaded succesffully! You can now invoke it with -m en-et-tiny\n```\n\n## Removing models from the CLI\nModels can be removed from the GUI or the CLI. For the CLI model removal, you need to:\n```bash\n./translateLocally -r en-et-tiny\nModel English-Estonian type tiny successfully removed.\n```\n\n## Listing available models\nThe avialble models can be listed with `-l`\n```bash\n./translateLocally -l\nCzech-English type: tiny version: 1; To invoke do -m cs-en-tiny\nGerman-English type: tiny version: 2; To invoke do -m de-en-tiny\nEnglish-Czech type: tiny version: 1; To invoke do -m en-cs-tiny\nEnglish-German type: tiny version: 2; To invoke do -m en-de-tiny\nEnglish-Spanish type: tiny version: 1; To invoke do -m en-es-tiny\nSpanish-English type: tiny version: 1; To invoke do -m es-en-tiny\n```\n\n## Translating a single sentence\nNote that customising the translator settings can only be done via the GUI.\n```bash\necho \"Me gustaria comprar la casa verde\" | ./translateLocally -m es-en-tiny\n```\n\n## Translating a whole dataset\n```bash\nsacrebleu -t wmt13 -l en-es --echo ref \u003e /tmp/es.in\n./translateLocally -m es-en-tiny -i /tmp/es.in -o /tmp/en.out\n```\n\nNote that if you are using the macOS translateLocally.app version, the `-i` and `-o` options are not able to read most files. You can use pipes instead, e.g.\n```bash\ntranslateLocally.app/Contents/MacOS/translateLocally -m es-en-tiny \u003c input.txt \u003e output.txt\n```\n\n## Pivoting and piping\nThe command line interface can be used to chain several translation models to achieve pivot translation, for example Spanish to German.\n```bash\nsacrebleu -t wmt13 -l en-es --echo ref \u003e /tmp/es.in\ncat /tmp/es.in | ./translateLocally -m es-en-tiny | ./translateLocally -m en-de-tiny -o /tmp/de.out\n```\n\n# NativeMessaging interface\ntranslateLocally can integrate with other applications and browser extensions using [native messaging](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging). This functionality is similar to using pipes on the command line, except that the message format is JSON which allows you to specify options per input fragment, and the translated fragments are returned when they become available as opposed to the input order.\n\n## Limitations\nRight now there is a 10MB message limit for incoming messages. This matches the limitations of Firefox. Responses are limited to about 4GB due to the native messaging message format.\n\n## Using NativeMessaging from Python\nStart translateLocally in a subprocess with the `-p` option, and pass it messages [formatted as described here](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging#app_side) to its stdin. All supported messages are described in the [NativeMsgIface.h](src/cli/NativeMsgIface.h) file.\n\nThere is an example, [native_client.py](scripts/native_client.py), that demonstrates how to use translateLocally as an async Python API.\n\n## Using NativeMessaging from browser extensions\nRight now, the functionality is only automatically available to Firefox and Chrome.\n\ntranslateLocally automatically registers itself with Firefox when you start translateLocally in GUI mode. Then you can install the [Firefox translation addon](https://github.com/jelmervdl/firefox-translations/releases). After installation of the addon, go into the addon settings and pick \"translateLocally\" as translation provider.\n\n### Developing your own browser extension\nDue to the way Firefox and Chrome call translateLocally, you will need to add your browser extension id to the translateLocally source code before it is able to accept native messages.\n\nAdd your extension id to [constants.h](src/constants.h) and rebuild translateLocally from source. Once you start it in GUI mode, it will re-register itself with support for your extension.\n\nIf you want your extension id added to translateLocally permanently, please open an issue or send us a pull request!\n\n# Importing custom models\ntranslateLocally supports importing custom models. translateLocally uses the [Bergamot](https://github.com/browsermt/marian-dev) fork of [marian](https://github.com/marian-nmt/marian-dev). As such, it supports the vast majority marian models out of the box. You can just train your marian model and place it a directory. \n## Basic model import\nThe directory structure of a translateLocally model looks like this:\n```bash\n$ tree my-custom-model\nmy-custom-model/\n├── config.intgemm8bitalpha.yml\n├── model_info.json\n├── model.npz\n└── vocab.deen.spm\n```\nThe `config.intgemm8bitalpha.yml` name is hardcoded, and so is `model_info.json`. Everything else could have an arbitrary name. translateLocally will load the model according to the settings specified in `config.intgemm8bitalpha.yml`. These are just normal marian configuration options. `model_info.json` contains metadata about the model:\n```bash\n$ cat model_info.json \n{\n  \"modelName\": \"German-English tiny\",\n  \"shortName\": \"de-en-tiny\",\n  \"type\":      \"tiny\",\n  \"src\":       \"German\",\n  \"trg\":       \"English\",\n  \"version\":   2.0,\n  \"API\":       1.0\n}\n```\nOnce the files are in place, tar the model:\n```bash\n$ tar -czvf my-custom-model.tar.gz my-custom-model\n```\nAnd you can import it via the GUI: Open translateLocally and go to **Edit -\u003e Translator Settings -\u003e Languages -\u003e Import model** and navigate to the archive you created. \n\n## Quantising the model\nThe process described above will create a model usable by translateLocally, albeit not a very efficient one. In order to create an efficient model we recommend that you quantise the model to 8-bit integers. You can do that by downloading and compiling the [Bergamot](https://github.com/browsermt/marian-dev) fork of marian, and using `marian-conv` to create the quantised model:\n```bash\n$MARIAN/marian-conv -f input_model.npz -t output_model.bin --gemm-type intgemm8\n```\nAnd then changing your configuration `config.intgemm8bitalpha.yml` to point to this new model, as well as appending `gemm-precision: int8shift` to it.\n\n## Further increasing performance\n**For best results, we strongly recommend that you use student models.** Instructions on how to create one + scripts can be found [here](https://github.com/browsermt/students/tree/master/train-student) and a detailed video tutorial and explanations are available [here](https://nbogoychev.com/efficient-machine-translation/). Student models are typically at least 8X faster than teacher models such as the transformer-base preset.\n\nYou can further achive another 30\\%-40\\% performance boost if you precompute the quantisation multipliers of the model and you use a lexical shortlist. The process for those is described in details at the Bergamot project's [Github](https://github.com/browsermt/students/tree/master/train-student#5-8-bit-quantization). Remember that you need to use the [Bergamot](https://github.com/browsermt/marian-dev) fork of Marian.\n\nExample 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).\n\n## External repositories\nWe support custom repositories. You can add a custom repository from the Settings-\u003eRepositories menu. An example repository file can seen [here](https://translatelocally.com/models.json). Currently available repositories:\n- Bergamot: https://translatelocally.com/models.json\n- OpusMT: https://object.pouta.csc.fi/OPUS-MT-models/app/models.json\n- HPLT: https://raw.githubusercontent.com/hplt-project/bitextor-mt-models/refs/heads/main/models.json\n\nThe Bergamot repository is the one used by default. The OpusMT one needs to be added by the user, if the user desires to do so.\n\n# Acknowledgements\n\u003cimg src=\"https://raw.githubusercontent.com/XapaJIaMnu/translateLocally/master/eu-logo.png\" data-canonical-src=\"https://raw.githubusercontent.com/XapaJIaMnu/translateLocally/master/eu-logo.png\" width=10% /\u003e\n\nThis project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 825303.\n\n## Bergamot\nThis project was made possible through the combined effort of all researchers and partners in the Bergamot project https://browser.mt/partners/ . The translation models are prepared as part of the Bergamot project https://github.com/browsermt/students . The translation engine used is https://github.com/browsermt/bergamot-translator which is based on marian https://github.com/marian-nmt/marian-dev .\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FXapaJIaMnu%2FtranslateLocally","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FXapaJIaMnu%2FtranslateLocally","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FXapaJIaMnu%2FtranslateLocally/lists"}