tc2rc

README

go-tc2rc

Go library and CLI for converting translationCore (tc) repositories to Resource Container (RC) repositories.

A tc repo is a single-book scripture project (subject "Aligned Bible"): a manifest.json, one exported USFM file named after the repo (e.g. as_irv_1th_book.usfm), and tool data (alignment JSON, settings.json) that is not carried into the RC.

Combined with go-rc2sb, this completes the pipeline that turns any tc repo on DCS into a Scripture Burrito (SB):

tc2rc <tcDir> <rcDir>
rc2sb <rcDir> <sbDir>

Library

import tc2rc "github.com/unfoldingWord/go-tc2rc"

rep := tc2rc.Convert(ctx, inDir, outDir, tc2rc.Options{})
if !rep.OK {
    log.Fatal(rep.Error)
}

Options.RepoName overrides the DCS repo name used to locate the exported USFM file when the input directory's basename differs from the repo name.

CLI

go install github.com/unfoldingWord/go-tc2rc/cmd/tc2rc@latest

tc2rc [--repo-name <name>] <tcRepoDir> <rcOutDir>

A conversion report is written to <rcOutDir>.report.json. Exit code is 0 when a usable RC repo was produced, 1 otherwise.

What the conversion does

1. manifest.json → manifest.yaml — Dublin Core fields are built from the tc manifest: resource.id becomes the RC identifier, target_language becomes the language block, license becomes rights, tsv_relation becomes relation, source_translations becomes source, and the subject is always Aligned Bible.
2. USFM selection — tc repos usually hold two .usfm files: the tc export named after the repo and a copy named after the book. Selection priority: <repoName>.usfm, then <book>.usfm (e.g. amo.usfm for Amos), then the first .usfm file in the repo root. Repos with no .usfm file fail to convert.
3. Localized book title — read from the USFM \mt, \mt1, or \h marker (in that order), falling back to target_language.book.name, project.name, then the canonical English name. Used for the RC project title (and the manifest title when resource.name is empty).
4. File relocation — the selected USFM is copied to <BOOK>.usfm (e.g. 1TH.usfm); the single manifest project entry points at it with the correct sort, versification (ufw), and category (bible-ot/bible-nt). Alignment JSON directories and settings.json are not carried over.
5. License/README — LICENSE.md and README.md are copied through; when the tc repo has no license file, the standard unfoldingWord CC BY-SA 4.0 LICENSE.md is written.

Finding tc repos on DCS

curl "https://git.door43.org/api/v1/repos/search?metadataType=tc"

scripts/fetch_tc_repos.py pages through that endpoint and clones every tc repo into a target directory:

python3 scripts/fetch_tc_repos.py --dest /tmp/tc_repos --limit 100

Build & Test

go build ./...
go test ./...
go vet ./...

Documentation

Overview

Package tc2rc converts translationCore (tc) repositories to Resource Container (RC) format.

Index

• func WriteReport(rep *Report, path string) error
• type Options
• type Report
  • func Convert(ctx context.Context, inDir, outDir string, opts Options) *Report
  • func (r *Report) Warnf(format string, args ...any)
• type Result
  • func ResultFromReport(rep *Report) Result

Functions

func WriteReport

func WriteReport(rep *Report, path string) error

WriteReport writes the conversion report as JSON to path.

Types

type Options

type Options struct {
	// RepoName overrides the repo name used to locate the exported USFM file
	// (<RepoName>.usfm). If empty, the basename of the input directory is used.
	RepoName string
}

Options configures a translationCore to RC conversion.

type Report

type Report struct {
	// Source is the input translationCore directory.
	Source string `json:"source"`

	// Output is the output RC directory.
	Output string `json:"output"`

	// Book is the lowercase book code converted (e.g. "jon").
	Book string `json:"book"`

	// TCVersion is the manifest tc_version.
	TCVersion int `json:"tc_version"`

	// USFM is the source .usfm filename selected from the tc repo.
	USFM string `json:"usfm"`

	// OK is true when a usable RC repository was written.
	OK bool `json:"ok"`

	// Error is set when OK is false.
	Error string `json:"error,omitempty"`

	// Warnings are non-fatal issues encountered during conversion.
	Warnings []string `json:"warnings,omitempty"`
}

Report is the fail-safe conversion record for one tc → RC conversion. Check OK to determine whether a usable RC repo was produced.

func Convert

func Convert(ctx context.Context, inDir, outDir string, opts Options) *Report

Convert converts one translationCore repository at inDir into an RC repository at outDir.

It never panics. Failures are recorded on the returned Report (OK == false). Warnings are non-fatal. On hard conversion failure the incomplete outDir is removed.

The resulting RC (subject "Aligned Bible", one book per repo) is suitable for conversion to Scripture Burrito via github.com/unfoldingWord/go-rc2sb.

func (*Report) Warnf

func (r *Report) Warnf(format string, args ...any)

Warnf appends a formatted warning to the report.

type Result

type Result struct {
	// Book is the lowercase book code converted.
	Book string

	// TCVersion is the manifest tc_version.
	TCVersion int

	// InDir is the input translationCore directory.
	InDir string

	// OutDir is the output RC directory.
	OutDir string

	// Warnings is the list of non-fatal conversion warnings.
	Warnings []string
}

Result holds summary information about a completed conversion. It mirrors go-rc2sb's Result shape for library consumers.

func ResultFromReport

func ResultFromReport(rep *Report) Result

ResultFromReport builds a Result summary from a completed Report.