Repository files navigation

Translate is a powerful translation extension for Albert launcher that uses the new version 3 beta of Google'sCloud Translation API to solve the problems of rate limiting faced by the included translation extensions.

• Installation
  • Installing with Dark Icon
  • Authenticating with Google Cloud API
• Basic Usage
  • Actions
  • Advanced Usage Examples
    • Translating Into a Different Language
    • Overriding The Detected Language
    • Translating Into Multiple Languages
    • Smart Translation
• Configuration
  • Example Config
  • Available Options
    • API Config
    • Extension Config
• Supported Language Codes
• License
• Contributing

Albert Translate utilises version 3 of the Google Cloud Translate API -- provided by thegoogle-cloud-translatePython package -- which can be installed with Pip before cloning this extension:

pip install --user google-cloud-translategit clone https://github.com/dshoreman/albert-translate.git

You can then install Albert Translate either globally or for only your user:

cd albert-translate# Local install (installs to ~/.local/share/albert)make install# Global install (installs to /usr/share/albert)PREFIX=/usr make install

Once installed, open Albert's config window and enable Translate in the Python section of the Extensions tab.

NOTE: This extension uses the same trigger as the built-inGoogle Translate extension.
Albert will only "see" the first enabled extension for a given trigger in order to prevent collisions.
If you used it previously,Google Translate must be disabled prior to using this extension.

The above steps will install a white icon by default which should work well with most dark-themed Albertinstances. If you're using a theme that shows dark icons better, you can instead install the black icon:

cd albert-translateICON=dark make install

While the v3beta version of Google Cloud's Translation API has a free tier, it requires a Service Account inorder to use it. Follow the steps below to create a project and service account for use with Albert Translate:

1. Create a project and take a note of theProject ID -- you'll need it later
2. Enable theCloud Translation API for your project

   You will need to enable billing for the project, despite only using the free tier.

3. Create a service account and save your Service Key JSON file somewhere safe.

   Add theCloud Translation > Cloud Translation API User role so it can use the API.

4. Finally, set theProject ID andService Key path in your config file and restart Albert.

The trigger for Albert Translate istr -- the same as the Google Translate extension it replaces. Withoutchanging any of the extension options in yourconfiguration, you can translate any text into English simplyby typingtr The text you wish to translate into Albert. The API will automatically detect the source language.

When you've translated some text, there are two actions available. The primary action when you press enterwill copy the translated text to your clipboard so that you can paste it into another application.

You can also open the query in Google Translate by pressingAlt and selectingView in Google Translate.
This will open Google Translate with the same source and target languages that you set in your query.

While this extension can be useful without setting any special options, it can be much more powerful whenused with the inlineto andfrom options. The following examples highlight some common scenarios:

There may be times where Google Translate detects the wrong language, particularly if the text you'retranslating contains more than one language or is similar to another language.

To get around this, you can usefrom:<language-code> to set your own source language:

It is possible to translate into languages other than English by manually specifying the language code you wishto translate into withto:<language-code>, e.g.tr to:fr Hello, world! to translate into French:

You can translate text into multiple languages by separatingsupported language codes with a comma:

Unlike the Google Translate extension included with Albert, theto andfrom options can be given in anyorder -- or indeed omitted entirely:

If you commonly translate between two languages, Albert Translate can be configured in such a way that youwon't need to pass theto: andfrom: options every time you translate something.

For example, you may want to translate between English and French. If you settarget_lang = en,fr in yourconfig file then -- as long assource_lang is set toauto -- you can translate seamlessly between the two:

When Albert Translate is installed and enabled, it will create its config file in~/.config/albert/translate.ini.

It will automatically be filled with sensible defaults for the translation options, but you will need to set therequired options yourself. Typetr into Albert (followed by a space) to trigger the extension, then press enterto run the default action which is to open the config file in your editor.

The config file is written in an INI format with two sections. For details of each option, seeAvailable Options.

[api]project_id = my-projectservice_key = ~/Downloads/my-project-ea3198523091.json[extension]source_lang = autotarget_lang = en,fr

The[api] section contains options specific to the Google Cloud Translation API, used for authentication.

Your Project ID can be obtained from the project'sDashboard on Google Cloud Platform.
Before you use the project for this extension, make sure you have enabled theCloud Translation API.

If you don't yet have a project, seeAuthenticating with Google Cloud API for more details.

This is the absolute path to the JSON key file you saved after creating a Service Account for your project. Ifyou don't set this option, you must provide the path with theGOOGLE_APPLICATION_CREDENTIALS environmentvariable instead by starting Albert withGOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json albert.

For information on how to create a Service Account, seeAuthenticating with Google Cloud API.

The[extension] section contains options used to customise the default behaviour of the extension itself.

This option's value will be used as a fallback when you don't specifyfrom:<lang_code> before the text youwant to translate in Albert. If you often translate from different languages, this is best set toauto so thatthe Translation API can automatically detect the source language.

Defaults toauto

This is a list of languages to translate into by default when you don't specifyto:<lang_code> in the query.Multiple languages can be set by using a comma-separated list such asen,fr,de to translate into more thanone language without having to trigger the extension once for each language.

Defaults toen

For a list of supported language codes, seeLanguage Support in Google Cloud Docs.

• All code is licensed under version 2 of the GPL. Full license details can be found inLICENSE.md
• Icon used isTranslation by Ilsur Aptukov from the Noun Project

If you have any ideas you'd like to see implemented, feel free toopen an issue -- or send a pull request ifyou know how to code in Python. Hopefully there are no bugs, but if youdo manage to find one, run Albert fromthe command line so you can see any error messages then create an issue. I'll respond as soon as I can, butplease provide as much detail as possible so that it's easier to reproduce and fix the bug.

Found this project useful? Please consider donating viaBeerpayorLiberapay. All donations are appreciated,no matter how small. If you'd prefer to just say thanks, my GitHub username is also my nick on Freenode.