The Transconv package for LuaTeX

The Transconv package for LuaTeX aims to make the use of transcriptions in LaTeX easier.

As it is, there are two main problems concerning transcriptions:

1. The transcription scheme of choice might be annoying to input (requiring the frequent use of macros to input characters which might not be accessible on the keyboard), and
2. There are often multiple competing schemes for the same language, so an author who was originally using scheme x might find themselves having to switch to scheme y. In practice this amounts to manually track down and change every place where x was used – which of course is both tedious and error-prone.

Transconv solves these problems by:

• letting the user write in a transcription scheme which is easier to input (normally pure ASCII) and have the package handle the conversion to the actual output scheme with diacritics etc., and
• abstracting the actual scheme itself away from the text. This allows the user to switch schemes by simply changing an option.

For instance, if I had to transcribe the Southern Min word for “fifteen” in the Tâi-lô scheme (tsa̍p-gōo), I would normally have to write:

tsa\symbol{"030D}p-g\={o}o

But Transconv allows me to simply use numbers instead of the tone diacritics and write:

\tonan{tsap8-goo7}

What's more, if I suddenly find myself having to use the Bbánlám pìngyīm transcription scheme instead, all I have to do is change a package option and recompile, and Transconv will output the correct Bbánlám pìngyīm version instead: zápggoô.

Usage

Assuming you have all the files in a location where LuaTex can find them (see Installation), you can set up Transconv for use in your document like so:

\usepackage[scheme = cmn.pinyin]{transconv}

Or alternatively:

\usepackage{transconv}
\TransconvUseScheme{cmn.pinyin}

This sets your default output scheme for Standard Chinese (cmn) to Hanyu Pinyin:

\tocmn{Ni3 hao3.} % output: Nǐ hǎo.

You can also set up multiple languages, secondary schemes for the same language (for example to compare them with each other in your text), and configure how the output is typeset. Confer the documentation for this.

Currently Supported Languages

Abbreviation	Language	Input Scheme	Supported Output Schemes
ara	Arabic	modified ArabTeX	DIN 31635 (ara.din, WIP)
cmn	Standard Chinese	modified Pinyin	Hanyu Pinyin (cmn.pinyin)
			Wade-Giles (cmn.wadegiles)
jpn	Standard Japanese	modified Hepburn	Hepburn (jpn.hepburn)
			Kunrei-shiki (jpn.kunrei)
			Nihon-shiki (jpn.nihon)
kor	Standard Korean	modified Revised	McCune-Reischauer (original) (kor.mcr)
			McCune-Reischauer (DPRK variant) (kor.mcr-n)
			McCune-Reischauer (ROK variant) (kor.mcr-s)
			Revised Romanisation (kor.revised)
nan	Hokkien/Southern Min	modified Tâi-lô	Bbánlám pìngyīm (nan.bp)
			POJ (nan.poj)
			Tâi-lô (nan.tailo)
			TLPA (nan.tlpa)
san	Sanskrit	modified Velthuis	IAST (san.iast)
yue	Cantonese	modified jyutping	Jyutping (yue.jyutping)

It is also possible to add more languages and schemes with just a limited amount of work.

Installation

Transconv uses Lua code for the conversion, so it will only work with LuaTeX!

Nix users can add Transconv to the package list in their document flake like so:

{
  description = "Transconv example document";
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05";
    transconv-flake.url = "github:sievertst/luatex-transconv";
  };
  outputs = {self, nixpkgs, transconv-flake }:
    let
      system = "x86_64-linux"; # or whatever your system is
      pkgs = nixpkgs.legacyPackages.${system};
      transconv = transconv-flake.packages.${system}.default;

      tex = pkgs.texliveBasic.withPackages (tl:
      [ 
        transconv 
        # tl.otherPackage
      ]);
      # or alternatively using the old texlive.combine interface:
      # tex = pkgs.texlive.combine
      # {
      #   inherit (pkgs.texlive) scheme-basic
      #   transconv
      #   # otherPackage
      #   ;
      # };

    in
    {
      packages.${system}.default = pkgs.stdenvNoCC.mkDerivation {
        pname = "some-document";
        version = "1.0";
        buildInputs = [ pkgs.coreutils tex ];      
        # rest of your document derivation
      };
    };
}

Non-Nix users need to copy the transconv.sty file as well as the transconv/ directory (found inside lua/) to a place where LuaTeX can find them. This can simply be your document's root directory. If you want to install Transconv system-wide, the suggested location for the sty file is within tex/latex/ local/ in your local texmf/ directory (typically found within your home directory).

The transconv/ folder can be placed in any directory in your kpathsea lua path. You can check that path with the following console command:

kpsewhich --show-path=lua

The suggested location is within scripts/kpsewhich/lua inside your local texmf/ directory.

If for some reason, you cannot get LuaTeX to find the lua module, you can consider using the luapackageloader package to manually modify the path.

Uninstallation

To uninstall Transconv, locate the transconv.sty file as well as the transconv/ lua package folder and delete them.