Translation Dictionary

Overview

The Admin interface provides functionality to import and export translation dictionaries as JSON files. This feature allows you to manage translations between different accounts and external systems.

Import Dictionary Feature

What is the Import Dictionary? The Import Dictionary feature allows administrators to upload a JSON file containing translation mappings between external system IDs and local IDs.

Supported Translation Types

The system supports the following translation types that can be imported:

Translation Type	Description	Maps To
`shapes`	Shape type translations	shapeTypes
`connections`	Connection translations	connections
`wells`	Well type translations	wellTypes
`layers`	Layer type translations	layerTypes
`assets`	Asset translations	assets
`sockets`	Socket/connector translations	connectors
`virtualAssets`	Virtual asset translations	virtualAssets
`wellBores`	Well bore type translations	wellBoreTypes
`wellBoreSegments`	Well bore segment type translations	wellBoreSegmentTypes
`designTypes`	Connection type translations	connectionTypes
`connectionSegments`	Connection segment type translations	connectionSegmentTypes
`definitionIds`	Metadata definition translations	metaData

JSON File Format

Required Structure

The JSON file must follow this exact structure:

{
  "translations": {
    "externalAccountId1": {
      "translationType1": {
        "externalId1": "localId1",
        "externalId2": "localId2",
        "externalId3": null
      },
      "translationType2": {
        "externalId4": "localId4"
      }
    },
    "externalAccountId2": {
      "translationType1": {
        "externalId5": "localId5"
      }
    }
  }
}

Example JSON File

{
  "translations": {
    "external-system-001": {
      "assets": {
        "ext-pump-001": "local-pump-123",
        "ext-valve-002": "local-valve-456",
        "ext-obsolete-item": null
      },
      "connections": {
        "ext-conn-001": "local-conn-789",
        "ext-conn-002": "local-conn-012"
      },
      "wells": {
        "ext-well-type-a": "local-well-type-production",
        "ext-well-type-b": "local-well-type-injection"
      }
    },
    "another-external-system": {
      "layers": {
        "ext-layer-001": "local-geological-layer-001"
      },
      "virtualAssets": {
        "ext-virtual-001": "local-virtual-asset-001"
      }
    }
  }
}

Field Descriptions

translations (required): Root object containing all translation mappings
externalAccountId: String identifier for the external system or account
translationType: Must be one of the supported types listed above
externalId: The ID used in the external system
localId: The corresponding ID in Field Activity Planner, or null to delete a mapping

Import Process

File Selection: Click the "Import Dictionary" button to open a file dialog
File Validation: The system validates:
- File format is valid JSON
- Required "translations" property exists
- All translation types are supported
- All localId values are valid (string, number, or null)
Data Processing: Valid translations are merged into the current account's translations
Save Operation: Changes are saved with undo/redo support and event emission
Confirmation: Success message shows the number of processed translation entries

Validation Rules

The import process enforces these validation rules:

File Format: Must be valid JSON
Structure: Must contain a "translations" root object
Translation Types: Only supported translation types are allowed
External Account IDs: Must be strings
External IDs: Must be strings
Local IDs: Must be strings, numbers, or null
Null Values: Use null to delete existing translation mappings

Error Handling

If validation fails, you'll receive detailed error messages indicating:

- The specific validation error
- The location of the error (account, translation type, external ID)
- A list of allowed translation types

Common errors include:

- Invalid JSON format
- Missing "translations" property
- Unsupported translation types
- Invalid data types for IDs

Data Merging Behavior

When importing translations:

Existing mappings: Will be overwritten with new values
New mappings: Will be added to existing translations
Null values: Will delete existing mappings
Empty objects: Translation types or accounts with no mappings will be removed

Data Merging Examples

Scenario 1: Overwriting Existing Mappings

Current translations in system:

{
  "external-system-001": {
    "assets": {
      "ext-pump-001": "old-local-pump-456",
      "ext-valve-001": "local-valve-123"
    }
  }
}

Imported JSON:

{
  "translations": {
    "external-system-001": {
      "assets": {
        "ext-pump-001": "new-local-pump-789"
      }
    }
  }
}

Result after import:

{
  "external-system-001": {
    "assets": {
      "ext-pump-001": "new-local-pump-789",
      "ext-valve-001": "local-valve-123"
    }
  }
}

The mapping for ext-pump-001 was updated, while ext-valve-001 remained unchanged.

Scenario 2: Adding New Mappings

Current translations in system:

{
  "external-system-001": {
    "assets": {
      "ext-pump-001": "local-pump-123"
    }
  }
}

Imported JSON:

{
  "translations": {
    "external-system-001": {
      "assets": {
        "ext-valve-002": "local-valve-456"
      },
      "connections": {
        "ext-conn-001": "local-conn-789"
      }
    },
    "new-external-system": {
      "wells": {
        "ext-well-001": "local-well-123"
      }
    }
  }
}

Result after import:

{
  "external-system-001": {
    "assets": {
      "ext-pump-001": "local-pump-123",
      "ext-valve-002": "local-valve-456"
    },
    "connections": {
      "ext-conn-001": "local-conn-789"
    }
  },
  "new-external-system": {
    "wells": {
      "ext-well-001": "local-well-123"
    }
  }
}

New mappings were added while preserving existing ones. A new external system and translation type were also created.

Scenario 3: Deleting Mappings with Null Values

Current translations in system:

{
  "external-system-001": {
    "assets": {
      "ext-pump-001": "local-pump-123",
      "ext-valve-001": "local-valve-456",
      "ext-obsolete-001": "local-obsolete-789"
    },
    "connections": {
      "ext-conn-001": "local-conn-012"
    }
  }
}

Imported JSON:

{
  "translations": {
    "external-system-001": {
      "assets": {
        "ext-obsolete-001": null,
        "ext-valve-001": null
      }
    }
  }
}

Result after import:

{
  "external-system-001": {
    "assets": {
      "ext-pump-001": "local-pump-123"
    },
    "connections": {
      "ext-conn-001": "local-conn-012"
    }
  }
}

The mappings for ext-obsolete-001 and ext-valve-001 were deleted, while other mappings remained intact.

Export Dictionary Feature

What is the Export Dictionary?

The Export Dictionary feature creates a downloadable JSON file containing all current translation mappings for the selected account.

Export Process

Click Export: Click the "Export Dictionary" button
File Generation: System creates a JSON file with:
- All current translation mappings
- Metadata about the export (account, date, totals)
Download: File is automatically downloaded with a timestamped filename

Export File Format

{
  "metadata": {
    "account": "Account Name",
    "accountId": "account-id-123",
    "exportDate": "2025-09-09T10:30:00.000Z",
    "totalTranslations": 150
  },
  "translations": {
    "external-system-001": {
      "assets": {
        "ext-pump-001": "local-pump-123"
      }
    }
  }
}

Export Filename Convention

Files are named using this pattern:

external-translations-{AccountName}-{YYYY-MM-DD}-{HHhMM}.json

Example: external-translations-MyAccount-2025-09-09-10h30.json

Troubleshooting

Import Issues

"Invalid translation type" error:

Check that all translation types in your JSON match the supported types exactly
Case-sensitive matching is required

"Invalid JSON format" error:

Validate your JSON using a JSON validator
Check for trailing commas, missing quotes, or bracket mismatches

"Failed to save translations" error:

Check account permissions
Ensure the account is not in read-only mode
Try refreshing and importing again