SVG Translation Tool

This tool extracts multilingual text pairs from SVG files and applies translations to other SVG files by inserting missing <text systemLanguage="XX"> blocks.

Installation

This tool requires Python 3.10+. Install the lightweight core dependencies with:

pip install CopySVGTranslation

Quick Start

The recommended API uses the class-based SVGTranslationExtractor and SVGTranslationInjector classes.

Extract translations from an SVG

from pathlib import Path
from CopySVGTranslation import SVGTranslationExtractor

extractor = SVGTranslationExtractor(
    svg_file_path=Path("examples/source_multilingual.svg"),
    case_insensitive=True,
)

result = extractor.extract()

if not result.error:
    print(result.to_json())
    # {
    #     "new": {"hello": {"ar": "مرحبا", "fr": "Bonjour"}, ...},
    #     "title": {...},
    #     "tspans_by_id": {...},
    #     "title_new": {...},
    # }

Inject translations into an SVG

from pathlib import Path
from CopySVGTranslation import SVGTranslationInjector

injector = SVGTranslationInjector(
    case_insensitive=True,
    overwrite=False,
    pretty_print=True,
)

translations = {
    "new": {
        "Hello": {"ar": "مرحبًا", "fr": "Bonjour"},
    }
}

result = injector.inject(
    inject_file=Path("examples/target_missing_translations.svg"),
    all_mappings=translations,
    target_path=Path("translated/target.svg"),
    save_result=True,
)

if not result.new_stats.error:
    print(f"Inserted: {result.new_stats.inserted_translations}")
    print(f"Updated:  {result.new_stats.updated_translations}")
    print(f"Skipped:  {result.new_stats.skipped_translations}")
    print(f"Languages: {result.new_stats.all_languages}")

Extracting and injecting in a single step

For convenience, the high-level workflow functions combine both phases:

from pathlib import Path
from CopySVGTranslation import svg_extract_and_inject

tree = svg_extract_and_inject(
    extract_file=Path("examples/source_multilingual.svg"),
    inject_file=Path("examples/target_missing_translations.svg"),
    data_output_file=Path("examples/data.json"),
    save_result=True,
)

if tree is not None:
    print("Injection completed!")

The helper stores the extracted phrases under Path("examples/data.json") and, when save_result=True, writes the translated SVG to output_dir=Path("./translated").

API Reference

SVGTranslationExtractor

The primary class for extracting translation data from SVG files.

from CopySVGTranslation import SVGTranslationExtractor

extractor = SVGTranslationExtractor(
    svg_file_path: str | Path,
    case_insensitive: bool = True,
)

result: ExtractorData = extractor.extract()

Parameters:

Returns: ExtractorData — a dataclass with the following fields:

Use result.to_json() to get a plain dictionary suitable for JSON serialization.

SVGTranslationInjector

The primary class for injecting translations into SVG files.

from CopySVGTranslation import SVGTranslationInjector

injector = SVGTranslationInjector(
    case_insensitive: bool = True,
    overwrite: bool = False,
    pretty_print: bool = True,
)

result: InjectorData = injector.inject(
    inject_file: Path | str,
    all_mappings: Mapping | None = None,
    target_path: Path | None = None,
    save_result: bool = False,
)

Constructor Parameters:

inject() Parameters:

Returns: InjectorData — a dataclass with the following fields:

InjectorStats fields:

Use result.new_stats.to_json() to get a plain dictionary of the stats.

ExtractorData

Dataclass returned by SVGTranslationExtractor.extract(). See the extractor documentation above for field details.

InjectorData

Dataclass returned by SVGTranslationInjector.inject(). See the injector documentation above for field details.

High-Level Workflows

svg_extract_and_inject()

Extract translations from one SVG and inject them into another in a single call.

from CopySVGTranslation import svg_extract_and_inject

tree = svg_extract_and_inject(
    extract_file: Path | str,
    inject_file: Path | str,
    output_file: Path | None = None,
    data_output_file: Path | None = None,
    overwrite: bool | None = None,
    save_result: bool = False,
)

svg_extract_and_injects()

Inject a pre-built translation mapping into an SVG file.

from CopySVGTranslation import svg_extract_and_injects

tree = svg_extract_and_injects(
    translations: Mapping,
    inject_file: Path | str,
    output_dir: Path | None = None,
    save_result: bool = False,
)

Legacy (Deprecated) Functions

⚠️ Deprecation Notice: The function-based extract() and inject() APIs are deprecated and will be removed in a future release. Migrate to SVGTranslationExtractor and SVGTranslationInjector respectively.

extract() (deprecated)

from CopySVGTranslation import extract

# Deprecated — use SVGTranslationExtractor instead
translations = extract(
    svg_file_path=Path("arabic.svg"),
    case_insensitive=True,
)

Migration:

# Before (deprecated)
from CopySVGTranslation import extract
translations = extract(svg_file_path=Path("arabic.svg"), case_insensitive=True)

# After (recommended)
from CopySVGTranslation import SVGTranslationExtractor
extractor = SVGTranslationExtractor(svg_file_path=Path("arabic.svg"), case_insensitive=True)
result = extractor.extract()
translations = result.to_json() if not result.error else None

inject() (deprecated)

from CopySVGTranslation import inject

# Deprecated — use SVGTranslationInjector instead
tree, stats = inject(
    inject_file=Path("target.svg"),
    all_mappings=translations,
    output_dir=Path("./translated"),
    save_result=True,
    return_stats=True,
)

Migration:

# Before (deprecated)
from CopySVGTranslation import inject
tree, stats = inject(
    inject_file=Path("target.svg"),
    all_mappings=translations,
    output_file=Path("translated/target.svg"),
    save_result=True,
    return_stats=True,
)

# After (recommended)
from CopySVGTranslation import SVGTranslationInjector
injector = SVGTranslationInjector(case_insensitive=True, overwrite=False)
result = injector.inject(
    inject_file=Path("target.svg"),
    all_mappings=translations,
    target_path=Path("translated/target.svg"),
    save_result=True,
)
tree = result.tree
stats = result.new_stats.to_json()

Data Model

The extractor produces a JSON document with these top-level keys:

{
    "new": {
        "normalized english text": {
            "ar": "Arabic translation",
            "fr": "French translation"
        }
    },
    "title": {
        "text without year": {
            "ar": "...",
            "fr": "..."
        }
    },
    "tspans_by_id": {
        "tspan-id": "Text content"
    },
    "title_new": {
        "text without year": {
            "ar": "...",
            "fr": "..."
        }
    }
}

Older exports may omit the wrapper and look like {"english": {"ar": "…"}}. The injector transparently accepts both structures, but the recommended format is the nested layout shown above.

Extract Example

Input SVG (arabic.svg)

<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg">
  <switch>
      <text id="t0-ar" systemLanguage="ar">
          <tspan id="t0-ar">الموسيقى في عام 2020</tspan>
      </text>
      <text id="t0-fr" systemLanguage="fr">
          <tspan id="t0-fr">La musique en 2020</tspan>
      </text>
      <text id="t0">
          <tspan id="t0">Music in 2020</tspan>
      </text>
  </switch>
  <switch>
      <text id="t1-ar" systemLanguage="ar">
          <tspan id="t1-ar">مرحبا</tspan>
      </text>
      <text id="t1-fr" systemLanguage="fr">
          <tspan id="t1-fr">Bonjour</tspan>
      </text>
      <text id="t1">
          <tspan id="t1">Hello</tspan>
      </text>
  </switch>
</svg>

Python code

from pathlib import Path
from CopySVGTranslation import SVGTranslationExtractor

extractor = SVGTranslationExtractor(
    svg_file_path=Path("arabic.svg"),
    case_insensitive=True,
)

result = extractor.extract()
print(result.to_json())

Extracted JSON

{
    "new": {
        "music in 2020": {
            "ar": "الموسيقى في عام 2020",
            "fr": "La musique en 2020"
        },
        "hello": {
            "ar": "مرحبا",
            "fr": "Bonjour"
        }
    },
    "title": {
        "music in": {
            "ar": "الموسيقى في عام",
            "fr": "La musique en"
        }
    },
    "tspans_by_id": {
        "t0": "Music in 2020",
        "t1": "Hello"
    },
    "title_new": {},
    "error": ""
}

Injection Example

Input SVG (target.svg)

<?xml version="1.0"?>
<svg xmlns="http://www.w3.org/2000/svg">
  <switch>
      <text id="t0">
          <tspan id="t0">Hello</tspan>
      </text>
  </switch>
  <switch>
      <text id="t1">
          <tspan id="t1">Music in 2020</tspan>
      </text>
  </switch>
</svg>

Python code

from pathlib import Path
from CopySVGTranslation import SVGTranslationInjector

injector = SVGTranslationInjector(
    case_insensitive=True,
    overwrite=False,
    pretty_print=True,
)

translations = {
    "new": {
        "hello": {"ar": "مرحبا", "fr": "Bonjour"},
        "music in 2020": {"ar": "الموسيقى في عام 2020", "fr": "La musique en 2020"},
    }
}

result = injector.inject(
    inject_file=Path("target.svg"),
    all_mappings=translations,
    target_path=Path("translated/target.svg"),
    save_result=True,
)

print(f"Inserted: {result.new_stats.inserted_translations}")
print(f"Languages: {result.new_stats.all_languages}")

Output SVG (translated/target.svg)

<?xml version='1.0' encoding='utf-8'?>
<svg xmlns="http://www.w3.org/2000/svg">
  <switch>
    <text id="t0">
      <tspan id="t0">Hello</tspan>
    </text>
    <text id="t0-ar" systemLanguage="ar">
      <tspan id="t0-ar">مرحبا</tspan>
    </text>
    <text id="t0-fr" systemLanguage="fr">
      <tspan id="t0-fr">Bonjour</tspan>
    </text>
  </switch>
  <switch>
    <text id="t1">
      <tspan id="t1">Music in 2020</tspan>
    </text>
    <text id="t1-ar" systemLanguage="ar">
      <tspan id="t1-ar">الموسيقى في عام 2020</tspan>
    </text>
    <text id="t1-fr" systemLanguage="fr">
      <tspan id="t1-fr">La musique en 2020</tspan>
    </text>
  </switch>
</svg>

Testing

Run the unit tests:

python -m pytest tests -v

Implementation Details

Text Normalization

The tool normalizes text by:

• Trimming leading and trailing whitespace
• Replacing multiple internal whitespace characters with a single space
• Optionally converting to lowercase for case-insensitive matching

ID Generation

When adding new translation nodes, the tool generates unique IDs by:

• Taking the existing ID and appending the language code (e.g., text2213 becomes text2213-ar)
• If the generated ID already exists, appending a numeric suffix until unique (e.g., text2213-ar-1)

Error Handling

The tool includes comprehensive error handling for:

• Missing input files
• Invalid XML structure
• Missing required attributes
• File permission issues
• Nested <tspan> structures (raises SvgNestedTspanExceptionError)
• Invalid SVG structures like <tref> elements (raises SvgStructureExceptionError)