Talkie

Text-to-speech (TTS) browser extension button

Talkie

Developer documentation

Talkie can be built and tested locally, using freely available open source tools.

About the source code

Find the source code in the Talkie repository on Github.
- The root directory mainly contains documentation; am trying to reduce technical files to keep it clean.
- Source code plus related technical files are in the ./code/ directory.
The main language is Typescript, with some supporting shell scripts and tooling.
- This is a monorepo, split up to several packages in the internal (non-published) @talkie/ scope/namespace. See ./packages/.
- Dependency graphs are generated in ./dist/graph at build time, to give an overview of internal package dependencies.
Talkie is free/libre open source software (FLOSS).
- The license is GNU General Public License version 3.0 (GPL-3.0); see also GPL on Wikipedia.
- All project contributors need to agree to the the Contributor License Agreement (CLA).

Prerequisites

A clone of the Talkie repository on Github.
- Many script commands rely on the repository and will not work for .zip release files with source code.
Development should be performed on modern Linux.
- Development on Apple macOS is not officially supported.
  - In particular, Talkie may use GNU-style --long-hand arguments incompatible with standard macOS shell commands.
- Development on Microsoft Windows is not supported.
  - Using Windows Subsystem for Linux (WSL) is not officially supported.
Use the develop branch as the base for your pull request.
- Follow the git-flow development procedure using git-flow.
- It is recommended to use gh for forking and creating pull requests on github.

Software requirements

The build process assumes that current stable versions of the following are available. If anything is missing from this list, please open an issue.

bash
dot from Graphviz.
git-flow (AVH Edition)
git
gh
jq
node, including npm and npx

Manual installation

Clone the repository.
Open a terminal and enter the ./code/ directory, which is the base directory for all commands unless otherwise noted.
Build the code using the script commands below.
From the browser extensions settings page:
- Enable developer mode.
- Load one of the output directories as an unpacked extension.
  - ./packages/output-webext-chrome/dist/webext/ for Google Chrome, Chromium, Vivaldi, and similar browsers.
  - ./packages/output-webext-webextension/dist/webext/ for Firefox, and other browsers.

Building

# Go to the directory where you cloned the repository.
cd talkie
cd code

# Make sure to start fresh.
git clean --interactive -x -d :/

# Install (exact) package dependencies and local development tools.
npm clean‐install

# Optionally reset local nx cache.
npx nx reset

# Do a clean build.
npm run --silent rebuild

Browser testing

Loads Talkie from the fresh build and allows for quick testing right in the browser.
Uses a temporary (empty) browser user profile, when possible.
Might not work on all systems; try to install/use another browser if one fails.

# Assumes you have `google-chrome`/`chromium`/`vivaldi` in your path.
cd ./packages/output-webext-chrome/
npm run --silent run:chrome
npm run --silent run:chromium
npm run --silent run:vivaldi

# Optionally use rainbow to highlight some of the Talkie log messages in the Chromium terminal output.
# https://github.com/nicoulaj/rainbow
npm run --silent run:chrome |& rainbow --red '"ERRO' --yellow '"WARN' --blue '"INFO'

# Open a new instance of Firefox, with an empty profile, and load Talkie in debugging mode.
cd ./packages/output-webext-webextension/
npm run --silent run:firefox

# You might need to set the path to Firefox on your system.
WEB_EXT_FIREFOX="${HOME}/Applications/Firefox.app/Contents/MacOS/firefox-bin" npm run --silent run:firefox

Build modes

It is possible to switch the build mode between production and development (default). Do this by setting the TALKIE_ENV environment variable at build time.

Production mode

The publicly published version, distributed to Chrome Web Store (CWS) and addons.mozilla.org (AMO).
Reduced default logging detail level to the developer console (see Debugging).
Uses minimized script files of dependencies, for reduced extension file size.

# Production build, for distribution.
TALKIE_ENV='production' npm run --silent rebuild

Development mode (default)

Increased default logging detail level to the developer console.
- Enables Redux action/state change logging.
Uses non-minimized development versions of script files of dependencies.
Enables <React.StrictMode> to track down potential problems.

# Default development build, including debugging features.
npm run --silent rebuild

Tooling

Per-package build cache

To speed up iterative development, package builds are parallelized and the input/output is cached. The build log output is hidden by by default, but may be helpful to review during build debugging.

# Output build log for debugging.
NX_VERBOSE_LOGGING='true' npm run --silent rebuild

Watch source files

Watch the source files for changes, and run the build when they do. Run in each package separately. Primarily used to detect build errors early.

npm run --silent watch

Linting

Primarily using XO for Typescript code linting, with some modified style rules. For lint fixes in VSCodium, install and configure vscode-linter-xo.

# Fix linting issues before committing.
npm run --silent lint

# Some lint can be fixed automatically.
npm run --silent lint:fix

Debugging

In-browser

Prefer using the development build.
From the browser extensions settings page:
- Enable developer mode.
- Inspect the Talkie background page view to see console output.
It is possible to coarsely adjust the console logging level.
- In the background page console, enter one of these logging level commands:
  - window.talkieServices.setLoggingLevel("TRAC"); (maximum logging)
  - window.talkieServices.setLoggingLevel("DEBG"); (default in development mode)
  - window.talkieServices.setLoggingLevel("INFO");
  - window.talkieServices.setLoggingLevel("WARN"); (default in production mode)
  - window.talkieServices.setLoggingLevel("ERRO");
  - window.talkieServices.setLoggingLevel("NONE"); (no logging)
You can also inspect the popup and options pages separately, to find problems specific to those parts. Most of the logging is duplicated to the background page console for an overview.
Optionally add breakpoints in the source code.

Translations

In order to offer Talkie in as many languages as possible, translations are automated. It is still possible — and preferred — to add overrides with human translations.

The _locales directory, usually present in the root of webextensions, is located inside a package.
- This is the base directory referenced below.
- The translation files are assembled before being copied to the webextension output packages.
During development, there translation placeholder methods may be used.
- Helps keeping track of which strings have not yet been translated.
- Inspect the debug output for warnings, both during build and in-browser.
Paths:
- Input: ./packages/shared-locales/src/data/_locales
- Output: ./packages/shared-locales/dist/data/_locales

Human translations

All message changes have to be reflected in ./_locales/en/base.json, which is the base for all other languages.
Translations can be done by editing or adding override.json for the desired locale in the _locales directory.
In case of doubt, please refer to ./_locales/en/base.json as the one source of truth when it comes to original message strings and descriptions.

Automated file mangling

The messages.json for each language is assembled by npm run --silent messages:refresh. It is fast enough for development change-test-change cycles.
All English base strings in ./_locales/en/base.json are automatically translated to all other languages by npm run --silent messages:download. It takes 1-3 minutes to translate all languages, and is too slow to use repeatedly during development. English is the easiest language to use during development.
Translation scripts require a Google Cloud Translation API key, jq, and some shell magic.
Automated file mangling is done by maintainers using npm run --silent messages:translate before each release where the have been text changes.

Translation file order

Translation files are merged in this order. The last value for a specific key/name wins, which means the messages in override.json are the most important.

Non-translated strings from ./_locales/en/untranslated.json.
Depends on the language; English has no modifications and uses the base:
- Non-translated strings from ./_locales/en/base.json.
- Translated strings from ./_locales/*/automatic.json.
Manual entries from ./_locales/*/manual.json.
Overrides from ./_locales/*/override.json.

Pull request procedure

These steps assume you are using the gh and git-flow tools.
Expect to have your contribution scrutinized, so make sure your code is well-written. You may be asked to fix some stuff before your pull request is accepted.

# Fork the repository to your user on github.
gh repo fork

# Switch to develop.
git checkout develop

# Start a new feature. Us a descriptive "<feature-name>", such as "automatic-language-detection".
git flow feature start <feature-name>

# Code your feature and add the files.
# Manually reload and test the code in the browser.
# Manually test all Talkie features:
#   - The Talkie button.
#   - Shortcut keys.
#   - Right click context menu.
#   - Options page.
#   - Language detection in more than one language.
#   - (Any features which might not have been added to this list.)
#   - (Any feature change you may have changed/added.)
# Test in the supported browsers:
#   - Google Chrome.
#   - Firefox.
#   - Preferably other browsers as well.

# Make sure the code builds.
npm run --silent rebuild

# Fix any warnings and errors before committing. See also linting.
npm run --silent test

# Commit your changes. Use a descriptive commit message, preferably with more than one line of text.
git commit

# Finish the feature.
git flow feature finish <feature-name>

# Publish the feature to your fork.
git flow feature publish <feature-name>

# Go to the repository page to create a pull request against the develop branch.
gh browse

Maintaining package dependencies

Keep package dependencies up to date and synchronized across monorepo sub-packages. These commands are helpful.

# List outdated packages, or version mismatches.
npm run --silent dependencies:check

# Update packages in-range.
# NOTE: major version upgrade are handled manually.
npm run --silent dependencies:upgrade

Release procedure

Packaging all extension variants for release in the different distribution channels, as well as a .zip file with the source code. These steps are only performed by the project owner.

# Finish up any features, switch to develop.
git checkout develop

# Ensure all strings have been translated.
# Check the diff as well as the final per-key message string count.
cd ./packages/shared-locales
npm run --silent messages:translate
cd -

# Ensure all files are included -- or excluded -- in the assembled extension output.
# This includes new code files/translations/resources added/removed since the last release.
cat ./packages/output-webext/src/package-files/*.txt

# Fix any warnings and errors before committing.
TALKIE_ENV='production' npm run --silent preoutput

# The "<release-version>" needs to follow semantic versioning, such as "v1.0.0".
# https://semver.org/
git flow release start <release-version>

# Update files to contain the version number.
npm run --silent version:update

# Finish the release and sign the tag.
git flow release finish -s <release-version>

# Check out the release version tag.
git checkout <release-version>

# Create zip files with the assembled extension outputs.
TALKIE_ENV='production' npm run --silent output

# Upload and publish the output where it can be automated.
# Release to other distribution channels manually.
npm run --silent publish:chromestore
npm run --silent publish:amo