Traduco — How to Use

Last Updated: January 1, 2025

Requirements

  • Autodesk Revit 2023, 2024, 2025, 2026, or 2027
  • An active Revit model (any discipline)
  • Optional: a Claude or OpenAI API key for AI-assisted translation
  • Internet access for AI translation (Review and Apply work fully offline)

Workflow Overview

1. Extract    →   2. Auto-Translate (optional)   →   3. Review   →   4. Apply   →   5. Validate

All commands are in the Avant Leap tab → Traduco panel.

Step 1 — Extract Model Text

Button: Extract Model Text (teal icon)

Scans the active Revit model and writes all translatable text to extraction.json.

What gets extracted (10 categories):

Category What it captures
Project Info Building Name, Project Name, Project Number, Status, Client, Address
Levels Level names
Views View names (templates and internal views are skipped)
Families Family names and type names
Element Types Non-family type names grouped by category
Instance Parameters Selected string parameters on placed elements (opt-in — slow on large models)
Type Parameters Selected string parameters on element types (opt-in — slow on large models)
Materials Material names
Text Notes Text content of text note elements
Schedule Headers Column headings of all non-template schedules

How to run:

  1. Open a Revit model.
  2. Click Extract Model Text.
  3. A category selection dialog appears — check the categories you want (Instance/Type Parameters are unchecked by default due to scan time).
  4. Click Extract. A progress window shows category-by-category progress.
  5. When complete, a summary shows how many strings were found per category.

Output file: {MyDocuments}\AvantLeap\Tools\Traduco\{ModelName}\{Year}\extraction.json

Step 2 — Auto-Translate (optional)

Button: Auto-Translate (purple icon)

Sends extracted strings to an AI provider and fills in translations automatically. You can skip this step and translate manually in Step 3.

How to run:

  1. Click Auto-Translate.
  2. Select source language and target language from the dropdowns.
  3. Select your AI provider (Claude or OpenAI).
  4. Paste your API key in the API Key field.
  5. Optionally enable Test Mode (amber checkbox) to run without making any API calls — useful for testing the workflow.
  6. Click Translate. A progress bar shows batch-by-batch progress.

What happens:

  • Entries already in the global dictionary are resolved instantly (no API call, no tokens).
  • Remaining entries are batched (50 per call) and sent to the AI provider.
  • Each successful batch updates the global dictionary for future reuse.
  • Translated entries receive status ai.

Output file: {MyDocuments}\AvantLeap\Tools\Traduco\{ModelName}\{Year}\{SRC}_{TGT}.json (e.g. ES_EN.json)

Global dictionary: {MyDocuments}\AvantLeap\Tools\Traduco\dictionary\{SRC}_{TGT}.json — shared across all models. Grows over time, reducing API costs.

Step 3 — Review Mapping

Button: Review Mapping (amber icon)

Opens a WPF grid where you can inspect, edit, and approve translations before applying them to the model.

How to use:

  1. Click Review Mapping.
  2. Select the language pair to review (e.g. ES → EN).
  3. The grid shows all entries: source text, AI-suggested translation, category, and status.
  4. Edit translations directly by clicking a cell in the Translation column.
  5. Mark entries as Skipped to exclude them from the Apply step.
  6. Use the Category and Status filters to focus on specific entries.
  7. Close the window — changes are saved automatically.

Entry statuses:

Status Meaning
pending Not yet translated
ai Filled by AI (review recommended)
dict Resolved from global dictionary
manual Edited by you
skipped Excluded from Apply

Step 4 — Apply Translation

Button: Apply Translation (red icon)

Writes translations from the mapping file back to the Revit model. This is the only step that modifies the model.

How to run:

  1. Click Apply Translation.
  2. Select the language pair to apply.
  3. Confirm the operation. A summary shows how many elements will be renamed.
  4. Click Apply. All changes are wrapped in a single TransactionGroup — one Undo step in Revit's undo history.

What gets written:

  • Entries with status ai, dict, or manual (non-empty translation) are applied.
  • Entries with status pending or skipped are left untouched.
  • Each entry targets the exact Revit element via stored ElementId — no name-matching ambiguity.

Known limitation — Shared Parameters: Changing the display name of a shared parameter requires re-creating the parameter. Traduco surfaces this as a warning and skips those entries rather than failing silently.

Step 5 — Validate Coverage

Button: Validate Coverage (blue icon)

Shows a coverage report comparing what was extracted vs. what is translated, per category.

Report columns:

Column Meaning
Category The extraction category
Total Total entries extracted
Translated Entries with a non-empty translation
Pending Entries with no translation yet
Skipped Entries marked as skipped
Coverage % Translated / (Total − Skipped)

Use this report to identify gaps before sharing the model or running Apply again.

Data Storage

All Traduco data is stored locally — no cloud sync, no external servers.

{MyDocuments}\AvantLeap\Tools\Traduco\
  {ModelName}\
    {Year}\
      extraction.json        ← source strings (regenerated on Extract)
      ES_EN.json             ← translation mapping for Spanish → English
      ES_PT.json             ← translation mapping for Spanish → Portuguese
      config.json            ← last used language pair, provider preference
  dictionary\
    ES_EN.json               ← global dictionary (shared across all models)
    ES_PT.json

API keys are held in memory only and never written to disk.

Tips

  • Run Extract again after model edits to refresh extraction.json. Your existing translations in {SRC}_{TGT}.json are preserved — only new strings are added as pending.
  • The dictionary grows over time. The more models you translate, the fewer API tokens subsequent runs consume.
  • Use Test Mode to verify the full workflow (Extract → Auto-Translate → Review → Apply → Validate) without spending API tokens.
  • One Undo step. The entire Apply operation is a single TransactionGroup in Revit — you can undo all renames with Ctrl+Z.

Troubleshooting

Issue Solution
Add-in doesn't appear in ribbon Verify the .addin file is in %APPDATA%\Autodesk\Revit\Addins\{Year}\
DLL not found error on Revit start Run deploylocal.bat after building
AI translation times out Reduce batch by checking fewer categories; large Instance/Type param scans can be slow
Schedule headers not applying The ColumnHeading setter behaviour varies by Revit version — check the Validate report
Missing translations after Apply Check Validate Coverage — entries may be pending or skipped