EDI Mini Translator — User Manual

Table of Contents

• 1. Overview
  • 1.1 What EDI standards are supported?
  • 1.2 Basic vs Pro license
  • 1.3 Installation
• 2. Main Window Layout
  • 2.1 Segment Tree columns
  • 2.2 Output Table columns
• 3. Loading an EDI File
  • 3.1 Inspecting segments
• 4. Building a Mapping
  • 4.1 Creating a mapping from scratch
  • 4.2 Saving and naming a mapping
  • 4.3 Loading an existing mapping
  • 4.4 Undoing mapping edits
  • 4.5 New Row Creator
• 5. Exporting CSV Output
  • 5.1 Batch translation (folder mode)
  • 5.2 Options relevant to export
• 6. Mapping Rules
  • 6.1 Opening the Rules dialog
  • 6.2 How rules work
  • 6.3 Adding and managing rules
  • 6.4 Conflict detection
• 7. Import / Export of Mappings
  • 7.1 Exporting a mapping
  • 7.2 Importing mappings
• 8. License
  • 8.1 Activating a Pro license
  • 8.2 Pasting an existing token
  • 8.3 Removing a license
  • 8.4 Expired or invalid tokens
• 9. Translation History
  • 9.1 Context menu actions
  • 9.2 Clearing the log
• 10. Tips & Troubleshooting
  • 10.1 Why is my CSV truncated to 50 rows?
  • 10.2 Why did "No Rule Matched" appear?
  • 10.3 How do I share mappings between computers?
  • 10.4 What if a parse error occurs?
  • 10.5 Where are application data files stored?
• 11. Keyboard Shortcuts
• 12. Glossary

1. Overview

Mini Translator is a desktop application for translating EDI (Electronic Data Interchange) documents into CSV format. It parses raw EDI files, displays their hierarchical segment/element structure, and lets you define named mappings that extract selected elements into columns of a CSV output file.

Tool designed to extract limited number of fields from EDI files.

The application runs as a desktop program on Windows, macOS, and Linux. No network access is required for normal operation; only license activation contacts the vendor's server.

1.1 What EDI standards are supported?

Mini Translator handles common X12-style EDI envelopes (ISA / GS / transaction sets such as 837, 835, 270, 271, 850, 810, 855, 997, etc.). The parser detects element (*) and sub-element (:) separators automatically from each file.

1.2 Basic vs Pro license

The application runs in Basic mode by default. A purchased Pro license unlocks higher limits and is indicated in the window title as "Etasoft Mini Translator — Pro License". See Section 8 — License for details on activating a Pro key and the feature differences between tiers.

1.3 Installation

Requirements

• Windows 11 or Windows server 2022
• Mac OS
• Linux desktop environment with X11 or Wayland support

Installing on Windows

Use the installer provided. Follow the standard installer prompts.

The application will appear in your desktop menu under Etasoft → Mini Translator.

Installing on Apple macOS

Unzip then drag "Mini Translator.app" into Applications.

Having "Mini Translator.app" in Applications may not be enough. Apple will quarantine the package. You can mark package as safe using few different methods.

One of the options is to use terminal command to remove quarantine attribute. Run xattr command in terminal from your home directory to enable the application.

xattr -dr com.apple.quarantine "/Applications/Mini Translator.app"

It is important to run command from your home directory.

Installing on Linux (Debian)

Run deb package installer or use command line:

sudo dpkg -i mini-translator_6.0.0_amd64.deb

2. Main Window Layout

The primary window is divided into two main panels, a toolbar at the top, and a status bar at the bottom.

Setup directories for input and output files.

Follow recommended steps:

1. Setup directories via Options screen
2. Setup at least one mapping using Mappings tab
3. Setup Rules to run specific mappings based on input file contents.

2.1 Segment Tree columns

The left-side TreeTableView shows four columns:

• ID — Internal segment/element identifier generated by the parser.
• Name — The semantic name of the element or sub-element (e.g., PO101, ST01). Bold rows are segments; indented lighter rows are elements and sub-elements.
• Req — Requirement code from the EDI definition (e.g., M for mandatory, C for conditional).
• Value — The actual value found in the loaded document.

2.2 Output Table columns

The right-side TableView lists every field that will appear as a CSV column:

• Segment ID / Element Index — Positional reference into the parsed tree.
• Name (editable) — Custom CSV header name. Double-click to edit inline. Leave blank to use the element's default display name.
• New Row Creator (checkbox) — When checked, a new output row starts every time this field receives a non-empty value after having already been populated in the current row. Useful for row-splitting on repeating transaction sets.
• Repeat Value If Empty (checkbox) — When checked and the source element is empty, the translator copies the value from the previous output row into the current one (fill-down behavior).

3. Loading an EDI File in Mappings

1. Click New in the toolbar (or use File → New / Ctrl+N).
2. In the file chooser, select an EDI file (*.edi, *.txt, *.x12, *.dat) and open it.
3. The application parses the file on a background thread; when complete:
   • The left panel populates with the segment tree.
   • You can start mapping.

If you load a different file later, all previous mapping state is cleared and you must rebuild or reload a mapping for the new file.

3.1 Inspecting segments

You can expand/collapse any segment node in the tree to view its elements and sub-elements. The Value column shows what the parser actually found; empty values mean that element was absent in this particular document.

4. Building a Mapping

A mapping is a named snapshot of which elements (and sub-elements) you want in your CSV output, together with their preferred column headers and row-splitting / repeat settings.

4.1 Creating a mapping from scratch

After loading an EDI file:

1. In the Segment Tree, check the checkbox next to any element or sub-element whose value should become a CSV column.
   • Checking a segment node selects all its descendants at once; unchecking deselects them.
2. As you check items, they appear in the right-side Output Table.
3. Double-click the CSV Field Name column of each row to give it a meaningful CSV header (for example, rename N101 to VendorID).
4. Set New Row Creator or Repeat Value If Empty as appropriate for your data shape.
5. When satisfied, click Save All on the toolbar (or use File → Save As).

Rename CSV fields by double-clicking on CSV Field Name column.

4.2 Saving and naming a mapping

• File → Save (Ctrl+S) — Saves under the currently active mapping name; if no name exists yet it invokes Save As.
• File → Save As (Ctrl+Shift+S) — Opens a dialog where you enter a new mapping name, then persists the current tree state and output-table configuration to the user-mappings file (minit_mappings.yaml under your application data directory).

The mapping list shown in the toolbar combo box is refreshed automatically after any save or import.

4.3 Loading an existing mapping

1. Use the Mappings combo box on the toolbar.
2. Select a saved name. The application restores:
   • The full segment/element tree (with all checkboxes re-checked as they were when saved).
   • All output-table rows, including custom CSV field names and checkbox flags.
   • The envelope metadata captured from the original source file (release, transaction number, sender/receiver IDs).

A snapshot of the restored state is kept in memory so that Undo All can revert any subsequent changes.

4.4 Undoing mapping edits

If you have modified the current tree or output table after loading a mapping:

• The Undo All button appears on the toolbar (grayed out until there are unsaved changes).
• Click it to restore the snapshot taken when the mapping was last loaded.
• You can also right-click anywhere in the Output Table and choose Save All from the context menu to persist your current edits instead of undoing them.

4.5 New Row Creator

New Row Creator checkbox helps align CSV output rows.

Important points:

1. Usually it should be set on only one CSV field.
2. You should pick a field that starts detail record in the EDI file, and is always present on every detail line.

Typical good examples for New Row Creator are first field of invoice detail, first field of purchase order detail, subscriber first name, first field of claim detail line in healthcare formats etc.

You may need to experiment and run number of translations to get output you want by adjusting what field in the output is set to be New Row Creator.

In this input file fields from LIN segment do not repeat on every detail but SHP 01 is always present. Based on this SHP 01 is better choice since missing LIN segment would cause CSV lines not to line up.

It is important to get new row creation right otherwise CSV fields will not line up across rows.

Pick big input files to confirm output fields line up correctly. Smaller input files may not reveal the issues.

Pick segment that is always present on every detail section in EDI file, and mark first element of that segment as "New Row Creator".

5. Exporting CSV Output

5.1 Batch translation (folder mode)

Batch mode translates every EDI file in a configured input folder and writes one CSV next to each source file:

1. Open Options (via the toolbar or File → Options) and set both an Input Directory and an Output Directory.
2. Place all .edi / .txt / .x12 / .dat files you wish to process into the input directory.
3. Click Translate. The application runs each file sequentially on a background thread, shows progress in the status bar, and writes one CSV per input file into the output directory.

Note: Batch mode requires that execution rules are configured (see Section 6 — Mapping Rules). Without rules, the batch dialog warns you to set up mappings first.

5.2 Options relevant to export

The Options dialog exposes two toggles:

6. Mapping Rules

Execution rules connect an incoming EDI envelope to a saved mapping automatically. They are consulted whenever you click Translate (both single-file and batch mode) after a file is loaded or processed in the batch loop.

6.1 Opening the Rules dialog

Choose File → Show Rules from the menu, or right-click an entry in the Translation History table and select Rules.

6.2 How rules work

Each rule ties a mapping name to one or more envelope qualifiers:

Rules are evaluated in table order; the first matching rule wins. When a match is found, Mini Translator loads that mapping into the tree and proceeds to CSV export (or skips it if no output fields were selected).

6.3 Adding and managing rules

1. Select a Mapping Name from the combo box, fill in Release / Transaction / Sender as needed, then click Add Rule.
2. Use Move Up / Move Down to reorder rules so that more-specific rules appear above broader ones.
3. Click a rule row and press Delete Rule to remove it.
4. After making changes, click Save to persist the rule list. The dialog closes on success.

6.4 Conflict detection

The Rules dialog monitors for overlapping rules — cases where two rules pointing at different mappings could match the same envelope. When detected, a warning label appears listing each conflicting pair so you can reorder or tighten one of them.

7. Import / Export of Mappings

Mini Translator stores all user mappings and rules in minit_mappings.yaml inside your application data directory (~/minit/ on most systems). You can back up, share, or migrate this file by exporting/importing through the UI.

7.1 Exporting a mapping

With a mapping selected in the toolbar combo box:

• Click Export Mapping on the toolbar (or use File → Export Mapping).
• Choose a destination for the .yaml file. The export writes the current mapping plus the entire active rule list into one portable document.

7.2 Importing mappings

1. Choose File → Import Mappings.
2. Select a previously exported .yaml file.
3. Mini Translator merges the imported entries and rules, refreshes the combo box, and reports success in the status bar.

Existing saved mappings are preserved; newly imported names take precedence if duplicates exist. If you need to clean up obsolete mappings, use Delete Mapping from the toolbar (available only when a mapping is selected).

8. License

Mini Translator ships in two tiers:

8.1 Activating a Pro license

1. Choose Settings → License.
2. In the dialog, paste or type your email address and click Activate.
3. If activation succeeds, the dialog shows a green "Pro license is active." message and the window title changes to include "Pro License". Your settings are saved automatically.

8.2 Pasting an existing token

If you already have a JWT token (for example from a previous installation or IT department), paste it into the Token text area in the License dialog and click the clipboard icon (or wait for auto-validation). The app decodes the payload and populates Application, Type, and Expiry read-only fields.

8.3 Removing a license

In the same License dialog, click Remove License. You will be prompted to confirm; upon confirmation the token is cleared and the application reverts to Basic mode immediately.

8.4 Expired or invalid tokens

If you paste an invalid or expired token, the status label turns red and explains the failure reason (for example, "License is not activated — it takes up to 24 hours after purchase"). The app falls back to Basic behavior; no functionality other than the row limit is lost.

When a Pro license has fewer than 10 days remaining, the status bar displays an orange warning: "Pro license expires in N day(s)." When the license expires, the application falls back to Basic-mode behavior — Pro-only features (acknowledgement generation, disable rules, custom rules) are disabled and toggle buttons become greyed out. No data is lost; you simply lose access to Pro features until the license is renewed.

9. Translation History

The Translation tab at the bottom of the main window records every successful CSV export:

9.1 Context menu actions

Right-click any history row to:

• Translate — Re-run the same batch or single-file operation immediately.
• Rules — Open the Rules dialog so you can adjust the matching rule that was used.
• Options — Open the Options dialog to change input/output directories or header behavior.
• Clear — Remove all history entries.

9.2 Clearing the log

You may also clear history from the toolbar via Clear History, which empties the table instantly (this action is not undoable).

10. Tips & Troubleshooting

10.1 Why is my CSV truncated to 50 rows?

If you are on a Basic license, each CSV export stops after 50 data rows and a warning label appears below the history table ("Basic license limit reached — CSV output truncated to 50 rows…"). Upgrade to Pro for unlimited translations, or reduce your input file size / add more granular rules to target smaller subsets.

10.2 Why did "No Rule Matched" appear?

The active envelope (release / transaction / sender) has no rule pointing at any saved mapping. Open the Rules dialog and either:

• Add a new rule with the correct qualifiers, or
• Use * as a wildcard to match broadly, then rely on the mapping you associate it with.

10.3 How do I share mappings between computers?

Export the current mapping (Section 7.1), copy the .yaml file to the other machine, and import it there (Section 7.2). The mapping file is fully self-contained; no database or registry keys need to be transferred.

10.4 What if a parse error occurs?

The status bar displays "Error: …" in red when the EDI parser encounters malformed segments (for example, an unexpected control character or mismatched element count). Check the raw file with a text editor; often correcting a stray separator resolves the issue. Mini Translator does not silently skip malformed records — it aborts translation of that file so you can inspect the problem before proceeding.

10.5 Where are application data files stored?

• Mappings: <appDataDir>/minit_mappings.yaml
• User settings (including license token): <appDataDir>/settings.properties
• Embedded H2 database (used internally by the parser): copied once to <appDataDir>/edistddb.mv.db from the classpath bundle and overwritten on first run.

The default app data location is ~/minit/ on Linux/macOS and %APPDATA%\minit\ on Windows. See the startup log for the exact resolved path if you need to back it up manually.

11. Keyboard Shortcuts

12. Glossary

• Segment — A named block in an EDI document (e.g., ISA, GS, ST, PO1).
• Element — A field within a segment, separated by the element delimiter (*).
• Sub-element — A component within a compound element, separated by the sub-element delimiter (:).
• Mapping — A named collection of selected elements/sub-elements plus CSV column definitions.
• Rule — An envelope-matching policy that automatically selects a mapping during translation.
• Pro license — The paid tier that removes the 50-row output limit and may unlock future advanced features.