plover-cycle-translations

Plover Cycle Translations

This Plover extension plugin contains a macro that allows you define multiple translations in a single outline, and then cycle through them Alt-Tab- or IME-style using a "selector stroke". It covers similar ground to Plover's retro_toggle_asterisk macro, but is broader in scope than just toggling between an outline and its asterisk-flagged equivalent (e.g. "HAOEU": "high" and "HAO*EU": "hi").

Cycling translations can be helpful for disambiguating between:

• homophones (words that are pronounced the same but differ in spelling; e.g. "sent", "cent", and "scent")
• words and their similar sounding proper nouns (e.g. "mark", "Mark", and "Marc")
• differences in regional spelling for the same word (e.g. "colour", "color")

These variants can be defined with a single outline, rather than needing to remember all their respective outlines. Alternatively, all of their original outlines can be edited or overridden to be cycleable, so it will not matter which variant's outline you stroke, you will always have the option to cycle.

For some examples of cycleable list entries to add to your own steno dictionaries that encompass all of the points above, see here.

Install

1. In the Plover application, open the Plugins Manager (either click the Plugins Manager icon, or from the Tools menu, select Plugins Manager).
2. From the list of plugins, find plover-cycle-translations
3. Click "Install/Update"
4. When it finishes installing, restart Plover
5. After re-opening Plover, open the Configuration screen (either click the Configuration icon, or from the main Plover application menu, select Preferences...)
6. Open the Plugins tab
7. Check the box next to plover_cycle_translations to activate the plugin

Usage

Using the "sent", "cent", and "scent" example above, the outlines for them in Plover theory are:

• "SEPBT": "sent" - indicative of a phonetic (how the word sounds) reading of "sent"
• "KREPBT": "cent" - indicative of an orthographic (how the word is spelled) reading of "cent", using the fingerspelled "C" KR chord
• "SKREPBT": "scent" - orthographic, similar to "cent"

If you wanted to standardise on the phonetic SEPBT outline for all three words, you could use this plugin to create a dictionary entry as follows:

"SEPBT": "=CYCLE:sent,cent,scent"

This will output "sent" when stroked. You then use a "selector stroke" to cycle to the next word in the comma-separated list of words, in the order they are defined. An example of a selector stroke dictionary entry would be:

"R*R": "=CYCLE:NEXT"

As you cycle through the word list, each outputted word gets replaced with the next word entry. Once you hit the end of the list, the cycle begins again: in the example above, if you stroke =CYCLE:NEXT when you have output "scent", it will be replaced with "sent".

If you have a particularly long list that you also want to cycle backwards through, you can use a "previous" selector stroke to do so, like:

"R*RB": "=CYCLE:PREVIOUS"

Cycleable dictionary entries are not limited to just single stroke outlines. Multiple stroke outline entries are also supported:

"ABG/SEL": "=CYCLE:axel,axle,axil"

Prefix and suffix entries are also supported:

"PW*EU": "=CYCLE:{bi^},by,buy,bye"

Non-text characters like emoji are also supported:

"H-PBD": "=CYCLE:👍,👎,👊"

Development

Clone from GitHub with git and install test-related dependencies with pip:

git clone [e-mail]:paulfioravanti/plover-cycle-translations.git
cd plover-cycle-translations
python -m pip install --editable ".[test]"

If you are a Tmuxinator user, you may find my plover-cycle-translations project file of reference.

Python Version

Plover's Python environment currently uses version 3.9 (see Plover's workflow_context.yml to confirm the current version).

So, in order to avoid unexpected issues, use your runtime version manager to make sure your local development environment also uses Python 3.9.x.

Testing

• Pytest is used for testing
• Coverage.py and pytest-cov are used for test coverage, and to run coverage within Pytest
• Pylint is used for code quality
• Mypy is used for static type checking

Currently, the only parts able to be tested are ones that do not rely directly on Plover.

Run tests, coverage, and linting with the following commands:

pytest --cov --cov-report=term-missing
pylint plover_cycle_translations
mypy plover_cycle_translations

To get a HTML test coverage report:

coverage run --module pytest
coverage html
open htmlcov/index.html

If you are a just user, you may find the justfile useful during development in running multiple code quality commands. You can run the following command from the project root directory:

just --working-directory . --justfile test/justfile

Deploying Changes

After making any code changes, deploy the plugin into Plover with the following command:

plover --script plover_plugins install --editable .

Where plover in the command is a reference to your locally installed version of Plover. See the Invoke Plover from the command line page for details on how to create that reference.

When necessary, the plugin can be uninstalled via the command line with the following command:

plover --script plover_plugins uninstall plover-cycle-translations