Interlinearizer

Interlinearizer extension for Platform.Bible

Installing a released build

To use the Interlinearizer without building it yourself, go to the releases page and follow INSTALL.md. Each release carries two assets: the extension itself (interlinearizer_<version>.zip) and the Paratext 10 Studio build it is meant to be used with. INSTALL.md walks through installing that application, dropping the extension zip into its extensions folder, and opening the Interlinearizer.

Windows and Linux — there is no macOS build, and the Linux build is a 64-bit Intel/AMD (amd64) snap. Attaching the application build to each release is temporary; once Paratext 10 Studio has publicly available releases of its own, the install docs will point there for it instead.

The rest of this README is for developing the extension from source.

Summary

The general file structure for an extension is as follows:

• INSTALL.md contains end-user instructions for installing a released build into Platform.Bible and opening the Interlinearizer. It is linked from the body of every release, so keep its GitHub URL stable
• package.json (and package-lock.json) contain information about this extension's npm package and lockfile. They are required for Platform.Bible to use the extension properly. The lockfile is project-specific and is not synced from the template. The built extension is copied into the build folder
• manifest.json is the manifest file that defines the extension and important properties for Platform.Bible. It is copied into the build folder
• src/ contains the source code for the extension
  • src/main.ts is the main entry file for the extension (registers commands and wires interlinear XML)
  • src/types/interlinearizer.d.ts is this extension's types file that defines how other extensions can use this extension through the papi. It is copied into the build folder
  • src/parsers/pt9/ contains parser and schema for parsing PT9 interlinear XML into structured data
  • *.web-view.tsx files will be treated as React WebViews
  • *.web-view.scss files provide styles for WebViews
  • *.web-view.html files are a conventional way to provide HTML WebViews (no special functionality)
  • src/__tests__/ contains unit tests (Jest) for the extension, including parser tests (valid and invalid XML, edge cases) and WebView tests
• __mocks__/ contains Jest mocks for the PAPI, file modules, and test fixtures used by tests in src/__tests__/. The @papi/backend and @papi/frontend mocks are used mutually exclusively (backend for main.ts tests, frontend for WebView tests); each mock file ends with export {} so TypeScript treats it as a module.
• assets/ contains asset files the extension and its WebViews can retrieve using the papi-extension: protocol, as well as textual descriptions in various languages. It is copied into the build folder
  • assets/displayData.json contains (optionally) a path to the extension's icon file as well as text for the extension's display name, short summary, and path to the full description file
  • assets/descriptions/ contains textual descriptions of the extension in various languages
    • assets/descriptions/description-<locale>.md contains a brief description of the extension in the language specified by <locale>
• contributions/ contains JSON files the platform uses to extend data structures for things like menus and settings. The JSON files are referenced from the manifest
• public/ contains other static files that are copied into the build folder
• test-data/ contains sample interlinear XML (e.g. Interlinear_en_MAT.xml) for development and tests
• .github/ contains files to facilitate integration with GitHub
  • .github/workflows contains GitHub Actions workflows for automating various processes in this repo (e.g. Test and Lint on push/PR to main, release-prep, hotfix-*; Publish and Bump Versions manual dispatch; CodeQL for security)
  • .github/assets/release-body.md is the template for the body of releases published using GitHub Actions. The Publish workflow substitutes its version placeholders into a copy outside the repo, and that copy plus a generated changelog becomes the release body
• dist/ is a generated folder containing the built extension files
• release/ is a generated folder containing a zip of the built extension files

See the Extension Anatomy wiki page for more information about the various files that comprise an extension and their relationships to each other.

To install

Install dependencies:

1. Follow the instructions to install paranext-core. We recommend you clone paranext-core in the same parent directory in which you cloned this repository so you do not have to reconfigure paths to paranext-core.
2. In this repo, run npm install to install local and published dependencies

Configure paths to paranext-core repo

If you cloned paranext-core anywhere other than in the same parent directory in which you cloned this repository, update the paths to paranext-core in this repository's package.json to point to the correct paranext-core directory.

To run

Running Platform.Bible with this extension

To run Platform.Bible with this extension:

npm start

Note: The built extension will be in the dist folder. In order for Platform.Bible to run this extension, you must provide the directory to this built extension to Platform.Bible via a command-line argument. This command-line argument is already provided in this package.json's start script. If you want to start Platform.Bible and use this extension any other way, you must provide this command-line argument or put the dist folder into Platform.Bible's extensions folder.

Building this extension independently

To watch extension files (in src) for changes:

npm run watch

To build the extension once:

npm run build

To package for distribution

To package this extension into a zip file for distribution:

npm run package

Testing

Unit tests

Unit tests use Jest and live in src/__tests__/. To run:

npm test                 # run all tests
npm run test:coverage    # run with coverage report (output to coverage/)

End-to-end tests

E2E tests use Playwright and live in e2e-tests/. They launch Platform.Bible with this extension loaded and verify behavior through the real UI.

Prerequisites:

• npm run build must have been run (dist/src/main.js must exist)
• paranext-core must have deps installed (e.g., with npm run core:install)

Smoke tests (self-contained, good for CI — launches and tears down Platform.Bible automatically):

npm run test:e2e:smoke

CDP tests (connect to an already-running app — faster for local development):

1. Start Platform.Bible with remote debugging enabled:

   npm run start:cdp

2. In a second terminal, run the tests:

   npm run test:e2e:cdp

New feature tests should use cdp.fixture and navigate entirely through visible UI. See e2e-tests/tests/_example/ for a reference template.

Publishing

These steps will walk you through releasing a version on GitHub and bumping the version to a new version so future changes apply to the new in-progress version. Publishing the release is what gives testers a public download link: the zip attached to a published GitHub release can be downloaded without a GitHub account, whereas an Actions build artifact cannot. INSTALL.md is the page to point testers at once a release is published.

1. Make sure the versions in this repo are on the version number you want to release. If they are not, manually dispatch the Bump Versions workflow or run the bump-versions npm script to set the versions to what you want to release on the branch you want to release from.

2. Manually dispatch the Publish workflow in GitHub Actions targeting the branch you want to release from. This workflow creates a new pre-release for the version you intend to release and creates a new bump-versions-<next_version> branch to bump the version after the release so future changes apply to a new in-progress version instead of to the already released version. This workflow has the following inputs:

• version: Enter the version you intend to publish (e.g. 0.2.0). This is simply for verification to make sure you release the code that you intend to release. It is compared to the version in the code, and the workflow will fail if they do not match.

• studioVersion: Enter the version of the Paratext 10 Studio build you are going to attach to this release (e.g. 0.5.0). The workflow substitutes it into the release body's install steps, so it has to be the version of the zip you actually attach. Leave blank if you don't know it yet, and the body keeps a <Studio version> placeholder for you to edit on the draft.

• newVersionAfterPublishing: Enter the version you want to bump to after releasing (e.g. 0.3.0-alpha.0). Future changes will apply to this new version instead of to the version that was already released. Leave blank if you don't want to bump.

• bumpRef: Enter the Git ref you want to create the bump versions branch from, e.g. main. Leave blank if you want to use the branch selected for the workflow run. For example, if you release from a stable branch named release-prep, you may want to bump the version on main so future development work happens on the new version, then you can rebase release-prep onto main when you are ready to start preparing the next stable release.

  [Optional] Create a new pre-release and bump versions branch manually

  Manually create a new pre-release and bump versions branch

  Alternatively, you can create a new pre-release manually:

  npm run package
  # Create a new pre-release in GitHub on tag `v<version>`
  # Copy `.github/assets/release-body.md` into the release body and fill in its placeholders by
  #   hand — the extension zip name, the INSTALL.md link tag, and `<Studio version>`; nothing
  #   substitutes them on this path
  # Press the "Generate release notes" button in the release creation page to generate a changelog
  # Attach contents of `release` folder to the release

  Then bump versions by running the following:

  npm run bump-versions <next_version>

  Or bump versions manually:

  git checkout -b bump-versions-<next_version>
  npm version <next_version> --git-tag-version false
  # Change version in the extension's `manifest.json`
  git commit -a -m "Bumped versions to <next_version>"; git push -u origin HEAD

3. Download the Windows and Linux Paratext 10 Studio builds that match this release. Studio builds are published on the paratext-10-studio releases page, a private repo — that link 404s unless your GitHub account has been granted access. The Publish workflow run's job summary records the exact paranext-core revision the extension was built against, which is the revision the Studio builds should come from.

4. Attach both Studio builds to the new draft release — Paratext.10.Studio.Setup.<Studio version>-Windows.zip and Paratext.10.Studio.Setup.<Studio version>-Linux.zip, since the install steps offer both platforms. They have to be uploaded by hand; the workflow attaches the extension zip and fills in its version, but nothing else. If you left studioVersion blank in step 2, also replace every <Studio version> in the release body with the version of the zips you attached — the install steps and the line naming the Studio build this release goes with. The body has to name the zips you actually attached.

5. Install the extension zip against at least one of the Studio builds and confirm the Interlinearizer tab renders, then adjust the draft release's body and other metadata as desired and publish the release. Until it is published it stays a draft, which is visible only to people with write access to this repo — publishing is what makes the zips downloadable by testers. Publishing also runs the Verify Release workflow, which fails if the body still has an unfilled <Studio version> or interlinearizer_<version>.zip placeholder, if its INSTALL.md link does not point at this release's tag, or if any of the zips the body names is not among the attached assets; all of these are fixable on the published release, and editing it runs the check again. Attaching an asset is not itself an edit, so if you publish before attaching the Studio builds, save any change to the release description afterwards to re-run the check against what is now attached.

6. Open a PR and merge the newly created bump-versions-<next_version> branch.

Bumping version without publishing a release

Sometimes, it may be useful to change the version without publishing a release.

To bump versions without publishing a release, manually dispatch the Bump Versions workflow in GitHub Actions targeting the branch on which you want to change versions. Alternatively, you can run the bump-versions npm script. This workflow will create a branch named bump-versions-<version> from the target branch (or, if running the script, your current head) with the needed changes. Open a PR and merge that new branch into the branch on which you want to change versions.

This workflow has the following inputs:

• newVersion: enter the version you want to bump to (e.g. 0.3.0-alpha.0). Future changes will apply to this new version instead of to the version.

For example, to bump branch my-branch to version 0.2.0, run the following:

git checkout my-branch
npm run bump-versions -- 0.2.0

Then create a PR and merge the bump-versions-0.2.0 branch into my-branch. my-branch is now ready for release.

Publishing problems

Following are some problems you may encounter while publishing and steps to solve them.

@swc/core Failed to load native binding

If you see the following error in the GitHub Actions workflow logs while packaging:

Module build failed (from ./node_modules/swc-loader/src/index.js):
Error: Failed to load native binding

Please see "Failed to load native binding" in the Troubleshooting guide for how to solve this problem.

To update this extension from the template

This extension project is forked from paranext-extension-template, which is updated periodically and will sometimes receive updates that help with breaking changes on paranext-core. We recommend you periodically update your extension by merging the latest template updates into your extension.

To set up this extension to be updated from the template, run the following command once after cloning this repo:

git remote add template https://github.com/paranext/paranext-extension-template

To update this extension from the template, make sure your repo has no working changes. Then run the following commands:

git fetch template
git merge template/main --allow-unrelated-histories

For more information, read the instructions on the wiki.

After updating this extension from the template, clear all temp/cache files and regenerate the extension's package-lock.json with this command:

npm run core:reinstall

Note: The merge/squash commits created when updating this repo from the template are important; Git uses them to compare the files for future updates. If you edit this repo's Git history, please preserve these commits (do not squash them, for example) to avoid duplicated merge conflicts in the future.

Special features in this project

This project has special features and specific configuration to make building an extension for Platform.Bible easier. Rather than duplicating the full explanation here, please refer to the Special Features in this project section of the multi-extension template README for details on these features.