TranslatorX user guide

Overview

Feature index

Use these groups to go directly to the workflow you need. The search box filters this guide by any visible term.

Modern foundation

A complete application rewrite

The current TranslatorX beta is a ground-up rewrite of TranslatorX Classic using modern frameworks. It is not a visual reskin: the application has been rebuilt while preserving the detailed protocol analysis and investigation workflows of the original.

The rewrite provides a maintainable cross-platform foundation that supports repeatable quality checks, safer incremental changes, more rapid feature development, and continued expansion without the constraints of the former application framework.

TranslatorX Classic remains available during the beta period. The new application preserves the core trace-analysis workflow while adding the capabilities linked throughout this guide.

First session

Getting started

The public beta is available for macOS and Windows. TranslatorX Classic remains available separately for macOS, Windows, and Linux.

1. Install TranslatorX. Choose the current signed package from the download page.
2. Open trace data. Drag files or folders onto the opening window, use the Open menu, or import copied text from the clipboard.
3. Narrow the message list. Search message content, hide protocols or routine traffic, or create structured filters.
4. Follow the call. Open Call Flow for the current display or use Call List to select a CDR call, SIP Call-ID, or correlated SIP session.
5. Review warnings. Open View > Event Log when a collection or import reports skipped data, inferred values, or cleanup warnings.

Import

Open traces

Files, folders, archives, and drag and drop

Use File > Open Files for a selected set or File > Open Folder to scan a directory tree. The folder dialog can limit the scan to common trace filenames and selected protocol families. Files and folders can also be dropped anywhere on the opening workspace.

The same detection pipeline handles plain text, gzip-compressed logs, ZIP bundles, ZIP files nested up to three levels, supported packet captures, and normalized .txtrace exports. Unsupported or undecodable entries are reported instead of silently becoming empty messages.

Packet captures

Supported classic PCAP and PCAPNG captures can contain Ethernet, stacked VLAN, Linux cooked, loopback, raw IPv4, or raw IPv6 traffic. TranslatorX reassembles IPv4 and IPv6 fragments and follows TCP sequence numbers across out-of-order segments and retransmissions before framing SIP with case-insensitive standard or compact Content-Length headers. A SIP header and SDP body may span packets or share one segment with another message. Truncated or malformed captures produce bounded warnings instead of a partial message being presented as complete.

Clipboard text

Choose File > Import from Clipboard after copying console output or a log excerpt. This is useful for CUBE and other command-line output that has not been written to a file.

Append, replace, and complementary sources

When a trace session is already open, Append adds the new data and rebuilds ordering, deduplication, call analysis, and correlation across the complete set. Replace starts a new session. Summary records from Unified CM calllogs can fill gaps when SDL messages are absent; if the matching full SDL message is added later, TranslatorX uses the full message instead of displaying a duplicate summary.

Loading progress

Folder discovery, file inspection, parsing, correlation, and call analysis have separate progress phases. Supported files are parsed concurrently with bounded worker counts so the interface stays responsive and memory usage remains controlled.

Translator window

The message workspace

The main table is the chronological view of decoded messages. Columns include normalized time, trace node, remote device, direction, protocol, message name, handle or tag, and call reference or Call-ID. Columns are resizable and can be auto-sized for long hostnames and IPv6 addresses.

Inspect decoded content

Select a row to show its detail below the list. SIP and SDP fields include contextual explanations without adding visual underlines to the message text. Q.931, SCCP, MGCP, H.225, H.245, RAS, and other supported protocols are decoded when the source contains enough data. Calllog-only records show a structured summary rather than fabricated SIP content.

Unified CM SIP normalization

Unified CM SDL traces can include the SIP message before and after a normalization script. TranslatorX keeps the message list wire-accurate by default: inbound rows show what Unified CM received before normalization, while outbound rows show what Unified CM sent after normalization. When semantic content actually changed, an indicator appears after the SIP message name.

Select the indicator or use the message detail control to open the normalization comparison. Inbound messages identify the wire representation as Wire (Before); outbound messages identify it as Wire (After). The Before, After, and Differences views make header, start-line, and body changes visible without adding a duplicate message row. Header ordering, capitalization, compact header names, folded-line formatting, newline style, and trailing blank body lines alone do not count as changes. SDL ...contd... records are reassembled before comparison.

Copy and open source data

Message content is selectable and can be copied. Table labels, controls, timestamps, and addresses are treated as interface elements rather than selection targets. Double-click a message to open its original source at the corresponding line.

Display controls

Use Display to show or hide protocol families and repetitive traffic such as SCCP or MGCP keepalives, SIP REGISTER, OPTIONS, and SUBSCRIBE/NOTIFY/PUBLISH. Display controls do not discard messages from the loaded session.

Narrow the trace

Filters and search

The toolbar search performs a case-insensitive text search across message data. Message Filters provide structured criteria for protocol, direction, message, node, endpoint, TCP handle, tags, Call-ID, Session-ID, call reference, correlation value, text, and time.

How filter rows combine

Criteria on one row are combined with AND. Separate rows are combined with OR. A message is visible when it satisfies every populated criterion on at least one row.

Quick and session filters

Select a message and use the Filter menu or detail actions to build a filter from its fields. Filtering a SIP session expands to the Call-IDs in the same explicit correlation component, so the Call List and message filter use the same relationship.

Enable, save, and reuse

Turn Filters enabled off to inspect the unfiltered session without deleting filter rows. Filter sets can be loaded from or saved to .txf files. Search, display controls, and filters continue to apply while live messages are arriving.

Original context

Source viewer

The source viewer opens the original file in a separate window and moves to the selected message. Long lines can be scrolled horizontally.

• Line numbers are enabled by default and can be hidden without changing the file.
• Search moves to the first match and provides previous and next controls.
• Matches only hides nonmatching lines until the option is turned off.
• Copying across lines excludes the line-number gutter.
• AI report citations can open an exact source line range, including raw evidence that is not a parsed message.

Ordering

Source time and timezone alignment

TranslatorX sorts the combined session by normalized GMT. It uses explicit UTC offsets, timezone text, protocol timestamps, device identity, and matching SIP messages across sources to estimate each file or device clock. Missing years are inferred from the imported session before falling back to the current year.

Open View > Source Times to review the offset, year, confidence evidence, files, and devices assigned to each source. Applying an override re-sorts the messages and rebuilds call and session analysis. The fallback GMT offset in Preferences is used only when stronger evidence is unavailable.

Ladder diagram

Call Flow and media streams

Open Call Flow from the toolbar or View menu. It uses the current search, filter, protocol, and routine-traffic settings and opens in a separate resizable window. The timestamp gutter remains visible while the diagram scrolls horizontally.

Signaling lanes and device aliases

Each lane has an address and a user-editable label. TranslatorX applies the same saved aliases in the main window and every Call Flow window. Reorder lanes with the header controls, or select adjacent lanes and combine them under a standalone label. Media-only addresses are kept adjacent to their related signaling device when the trace provides that relationship.

Message detail and export

Select an arrow to open its message in the resizable side inspector. Closing the inspector clears the selected-row highlight. A SIP BYE arrow includes its Reason and Warning header values when present, making disconnect context visible without opening the message; no annotation is added when those headers are absent. Use Export to save the complete diagram as SVG.

Negotiated RTP and SRTP

Show media streams is enabled by default. TranslatorX follows SDP offer/answer exchanges to the original offer endpoint before showing a stream, then displays the negotiated media type, RTP or SRTP transport, addresses, ports, and permitted direction. Re-INVITEs can show inactive, rejected, resumed, or changed media without duplicating an unchanged end-to-end stream. Audio, video, and other SDP media sections are handled through the same negotiation model when both sides are present.

Call List

Calls and SIP sessions

Call summaries are cached while traces load so opening Call List does not repeat the entire analysis. The window has three independent views:

SIP call outcomes distinguish completed, connected, cancelled, redirected, rejected, failed, and incomplete calls. Retransmitted initial INVITEs are collapsed for summary purposes, while unique re-INVITEs and all messages remain available in the trace and Call Flow.

Session Inspector

The Session Inspector opens separately and presents the observed route, chronological call legs, endpoint history, correlation evidence, and events such as initial INVITE, ringing, answer, new leg, transfer evidence, failure, and disconnect.

Summary records

CDR, CMR, and Unified CM calllogs

CDR and CMR data can be embedded in traces or opened from supported standalone files. The CDR detail window provides organized field groups, a raw field view, and field search.

Unified CM calllogs contain high-level SIP events but not complete wire messages. TranslatorX decodes the available event fields, endpoints, identifiers, direction, and status into a readable summary. These records participate in ordering and correlation and fill missing SDL events. A matching full SDL message takes precedence when both sources are loaded.

Reusable access

Profiles and secure connections

Open Profile Manager from the More menu or Preferences > Connections to add, edit, test, and remove Unified CM, CUBE, and Expressway profiles. Collection screens can create or update the same profiles, so there is one shared profile list throughout the application.

Create and verify a profile

1. Choose the product. Add a Unified CM, CUBE, or Expressway profile from Profile Manager or the relevant collection screen.
2. Enter the connection route. Supply the product address and port. For SSH products, leave SSH Route set to Direct or select a configured jump host.
3. Choose authentication. Configure the end device credentials independently from any jump-host credentials.
4. Test the connection. Confirm reachability, host or certificate trust, authentication, and product-specific prerequisites before relying on the profile during an incident.
5. Save the profile. The same saved profile becomes available to single-device, multi-device, troubleshooting, and supported live workflows.

Credential storage

Passwords, API keys, key passphrases, and optional CUBE enable passwords are stored in the operating system credential manager when saving is requested. Profile metadata does not contain the secret value.

SSH authentication

CUBE and Expressway connections support passwords, OpenSSH private keys, FIDO2 *_sk keys backed by a hardware authenticator, and keyboard-interactive authentication. TranslatorX prompts only when the server requests interactive input or user presence. Optional jump hosts use an independently configured username and authentication method. New SSH host keys must be reviewed before they are added to known_hosts.

Jump hosts

Open SSH Jump Hosts from the More menu or Preferences > Connections. Each jump host has its own address, username, authentication method, saved secret, and host-key trust. Test the jump host by itself before assigning it to a CUBE or Expressway profile.

1. Add and test the jump host. Complete any password, private-key, security-key, or keyboard-interactive MFA flow required by the intermediate host.
2. Select it on the device profile. Change SSH Route from Direct to the saved jump host. End-device credentials remain separate.
3. Test the complete route. TranslatorX authenticates to the jump host, opens the forwarded connection, then authenticates to the destination device.

HTTPS certificate review

Supported HTTPS APIs require TLS 1.2 or newer. If platform certificate validation fails, TranslatorX shows the certificate subject, issuer, validity, and SHA-256 fingerprint before credentials or trace evidence are sent. Accepting it stores an exact certificate pin for that origin. A changed certificate requires another review.

Test before collection

Use Test on a profile or jump host to verify network reachability and authentication. CUBE tests also inspect privilege access and VoIP trace status when applicable.

Historical logs

Single-device historical collection

Choose this workflow when the incident already happened and one product is the intended evidence source. Collection uses the configured download directory and accepts either a relative duration or an absolute start and end time. Successful results are imported automatically.

Run a single-device collection

1. Select the product and profile. Create or update the connection in place if it is not already saved.
2. Choose the interval. Use a relative duration such as the last 60 minutes, or enter an absolute start and end time.
3. Confirm the download directory. TranslatorX keeps downloaded source data there and imports supported results into the current workspace.
4. Start collection. Follow product-specific prompts for certificate or host-key trust, MFA, CUBE privilege, or VoIP trace prerequisites.
5. Review results. Successful messages load automatically. Open Event Log for skipped files, inferred clocks, partial results, or device-specific warnings.

Unified CM

Provide the publisher address and Serviceability credentials. TranslatorX discovers the cluster nodes and collects Cisco CallManager service traces from all nodes for the requested timeframe without requiring individual service or filename selection.

CUBE

Historical CUBE collection reads show voip trace cover-buffers, selects calls in the requested timeframe, and retrieves each call with show voip trace call-id. Cover-buffer timestamps are interpreted as UTC. TranslatorX checks show voip trace statistics; if VoIP trace is disabled, it can ask for permission to enable it before collection. An optional enable password can be used when the login does not begin at privilege level 15.

Expressway

TranslatorX can poll the persistent Network Log over SSH for a requested timeframe. Detailed network.sip records include full SIP messages when debug logging is enabled; INFO-level summaries can still provide limited call events when message bodies are unavailable. Diagnostic logging status is read before start or stop actions, and completed bundles are downloaded and imported. Modern and older Expressway trace layouts retain separate compatibility paths.

Multiple products

Multi-device collection and troubleshooting sessions

Both workflows combine evidence from several products. Use Multi-Device Collection for an interval that already exists; use a Troubleshooting Session when you are ready to reproduce the issue now.

Multi-Device Collection

1. Select saved profiles. Choose any combination of Unified CM, CUBE, and Expressway connections.
2. Set one timeframe. The same relative duration or absolute interval is applied to every selected profile.
3. Collect in parallel. Bounded concurrency prevents one slow target from blocking unrelated devices. The status view reports each profile independently.
4. Review the combined trace. Results are imported together so source-time alignment, deduplication, call analysis, and session correlation can operate across products.

Troubleshooting Session

1. Select participating profiles. Profiles can also be created from the troubleshooting screen.
2. Start the session. TranslatorX records the start time and starts the required Expressway diagnostic capture. If a prior Expressway capture is active, it is stopped before the new one begins.
3. Reproduce the problem. Keep the session limited to the time needed to capture the behavior.
4. Stop and collect. TranslatorX records the end time, stops managed capture state, collects every selected product for that exact interval, and imports the results together.

Warnings from one target do not replace successful results from the others. Open Event Log for per-device collection, authentication, clock, and cleanup details.

Real-time signaling

Live CUBE and Expressway traces

Start one or more CUBE and Expressway profiles together or add another source while a trace is already running. New messages are appended to the workspace and immediately participate in search, filters, call analysis, and open Call Flow windows.

CUBE live trace

CUBE uses debug ccsip messages and SIP transport data over SSH. TranslatorX gathers interface and socket context to improve source and destination addressing where standard SIP debug output does not contain it. Multiple CUBEs can run simultaneously.

Expressway live trace

Expressway live tracing polls the persistent Network Log. Full SIP bodies depend on the configured logging level; summary records remain useful when only INFO data is available.

Stop and cleanup

The live status control shows connected sources and message count. Stop ends every active source. For CUBE, TranslatorX requests that CCSIP message and transport debugs be disabled before disconnecting and reports cleanup that could not be confirmed.

Optional assistance

AI-assisted trace analysis

AI analysis is optional and does not replace deterministic parsing or protocol review. Start it from a SIP call, a correlated SIP session, or the current filtered message view. Describe the symptom and review the evidence set before sending it to the configured provider.

Providers and models

Provider keys are stored in the operating system credential manager. A provider can be tested, saved, or cleared independently.

Privacy controls

Authorization headers and SDP key material are always removed. Cloud analysis anonymizes telephone numbers, IP addresses, and hostnames by default; the user can disable identifier anonymization when approved for the selected account. Local Ollama analysis keeps original identifiers by default.

Evidence and additional context

The initial case includes stable evidence IDs, normalized timestamps, source IDs, and exact line ranges. The model is told that additional raw source data exists and can request literal or regular-expression searches across loaded files, then read exact line ranges before or after a match. It cannot browse arbitrary paths or request data outside the active trace catalog.

Reports, citations, and usage

The report includes probable cause, confidence, technical analysis, findings, alternatives, recommendations, and limitations. Evidence links open the corresponding message or raw source lines. TranslatorX displays accumulated input, output, cache-read, and cache-write tokens when the provider reports them. Private diagnostics record request progress and provider metadata without writing API keys or full generated report content.

Handoff

Export and share

File > Export Trace can export all loaded messages or only the currently displayed result after search, filters, protocol visibility, and routine-traffic controls.

The trace export formats do not retain the original source path or vendor log wrapper. Device aliases can be exported and imported separately as JSON from the Device Aliases window.

Application settings

Preferences and management windows

The More menu also opens Profile Manager, SSH Jump Hosts, Device Aliases, and Source Times. Device aliases are shared by the main workspace and every Call Flow window.

Release channels

Software updates

Automatic update checks are enabled by default and can be disabled in Preferences. Select Stable for public production releases or Beta for prerelease builds. Updates are downloaded only from the configured TranslatorX release feed and are verified with the application updater signature.

Manual Check for Updates is in the TranslatorX application menu on macOS and the Help menu on Windows. Platform installer signatures remain separate from the updater signature.

Background activity

Event Log

Open View > Event Log to review notices and warnings that should not occupy the main message workspace. Entries include skipped import sources, partial remote collections, inferred clock behavior, live-trace failures, debug cleanup warnings, and other background operations.

An Event Log warning does not necessarily mean the complete operation failed. Multi-device operations can retain successful results while recording a separate error for an unavailable target.

Compatibility

Supported data

Protocol coverage includes SIP/SDP, SCCP, Q.931/Q.SIG, MGCP, MGCP backhaul, H.225, RAS, and H.245. A source can be imported only to the level of detail it actually recorded.

Data protection

Security and privacy behavior

• Local file parsing, filtering, call correlation, call flow, and export do not require a cloud service.
• Saved secrets use the operating system credential manager rather than the profile or settings file.
• Supported HTTPS API connections require TLS 1.2 or newer, do not follow redirects, and use platform trust or an explicitly approved certificate pin.
• SSH uses reviewed host keys, supports separate jump-host credentials, and does not automatically trust an unknown key.
• Cloud AI analysis is user-initiated, strips credential material, and anonymizes identifiers by default. Local Ollama is restricted to loopback addresses.
• Application updates require the TranslatorX updater signature. macOS and Windows installers also use their platform signing systems.

These controls do not replace organizational policy. Trace and diagnostic files can still contain sensitive customer, user, network, and authentication data that must be handled appropriately.

Navigation

Keyboard, menus, and windows

Call Flow, Call List, Session Inspector, filters, source files, CDR detail, and management tools use separate native windows where appropriate. Closing the active secondary window does not clear the trace session. macOS keeps application actions in the TranslatorX menu; Windows uses the conventional File, View, Filter, Calls, and Help menus rather than an application-named menu.