Emd.Pacx.Plugins.AITranslator 1.2.4

🌍 Emd.Pacx.Plugins.AITranslator

Emd.Pacx.Plugins.AITranslator is a plugin for PACX that uses Azure OpenAI to automatically translate localized labels in Microsoft Dynamics 365 / Power Apps environments.

✅ Features

• Supports translation between any language pair supported by Azure OpenAI
• Efficient batch translation to optimize API calls
• Processes Excel sheets individually with optional custom rules
• Supports condition-based translation overrides via JSON rules (e.g., system fields)
• Allows prompt customization to guide translation behavior (e.g., glossary rules)
• Automatically generates and applies localized labels for D365 / Power Apps

⚙️ Installation

Make sure you have PACX installed on your system.

Install the AI Translator plugin with:

pacx plugin install -n Emd.Pacx.Plugins.AITranslator

📚 Available Commands

1. Manage Azure OpenAI Connections 🌐

Use connections to securely store your Azure OpenAI endpoints and keys.

pacx ai-translator conn [create] [delete] [list]

• create: Create and store a new Azure OpenAI connection.
• delete: Delete an existing Azure OpenAI connection by name.
• list: List all stored Azure OpenAI connections.

Create Connection

pacx ai-translator conn create --name <connection-name> --deploymentEndpoint <endpoint-url> --apiKey <api-key>

• --name (-n): [required] The connection name.
• --deploymentEndpoint (-de): [required] Azure OpenAI Deployment Endpoint.
• --apiKey (-ak): [required] Azure OpenAI API Key.

Delete Connection

pacx ai-translator conn delete --name <connection-name>

• --name (-n): [required] The connection name.

List Connections

pacx ai-translator conn list

2. Generate Translation Files ✨

Generates two Excel files:

• One with the original translations extracted from a solution.
• One containing newly generated translations by Azure OpenAI.

pacx ai-translator gen [options]

Options:

• --solutionName (-sn): [required] Name of the Solution.
• --sourceLanguageCode (-slc): [required] Source language code (e.g., 1033 for English).
• --targetLanguageCodes (-tlc): [required] The codes of the target languages comma-separated (e.g., 1040,1034 for Italian and Spanish, or 1040 for Italian only).
• --azureOpenAIConnection (-aoac): [required] Name of the Azure OpenAI connection.
• --sourceExcelPath (-sep): [optional] Existing Excel file to use instead of fetching from the environment.
• --attributeTranslationConstantsPath (-atcp): [optional] Path to a JSON file containing translation constants (for Attributes and Forms).
• --additionalPromptRequest (-apr): [optional] Additional instructions for the AI (e.g., "Always translate 'account' as 'Cliente'").
• --exportFolder (-ef): [optional] Path to export the files. Defaults to the current directory.
• --translationsBatchSize (-tbs): [optional] Number of rows to translate per batch sent to Azure OpenAI (default: 30). You can tune this for performance, but high values may exceed AI output limits and cause incomplete results.
• --exportOriginalOnly (-eoo): [optional] Export only the original translation file without applying any translations.
• --force (-f): [optional] Force translation even for labels that already contain a translated value. Useful if you want to overwrite existing translations with new ones.

The output files will be named using the following pattern:

• [SolutionName]_[TIMESTAMP]_original.xlsx
• [SolutionName]_[TIMESTAMP]_translated.xlsx

Example of generated file names:

• MySolution_20250429_121530_original.xlsx
• MySolution_20250429_121530_translated.xlsx

📝 Note: The generation (gen) and application (push) steps are intentionally separated. This allows you to review and validate the generated translations before applying them to your environment.

3. Push Translations 🚀

Applies the translations from a generated Excel file to the target environment.

pacx ai-translator push --translatedExcelPath <path-to-excel>

Options:

• --translatedExcelPath (-tep): [required] Path to the Excel file containing translations to apply.
• --importBatchSize (-ibs): [optional] Batch size used when importing translations into the target environment (default: 10). You can adjust this for performance, but too large values may lead to timeouts or API errors.
• --force (-f): [optional] Force import of translations even for labels that have not changed from the original. Useful to ensure all target values are updated regardless of differences.

📄 Attribute Translation Constants File

When using the --attributeTranslationConstantsPath option, you must provide a JSON file that defines constant translations for specific attributes.
This allows you to control exactly how certain technical fields are named and described.

The file must have this structure:

[
  {
    "FieldSchemaName": "createdby",
    "1040_DisplayName": "Autore creazione",
    "1040_Description": "Identificatore univoco dell'utente che ha creato il record.",
    "1034_DisplayName": "Autor de creación",
    "1034_Description": "Identificador único del usuario que creó el record."
  },
  {
    "FieldSchemaName": "createdon",
    "1040_DisplayName": "Data creazione",
    "1040_Description": "Data e ora in cui il record è stato creato.",
    "1034_DisplayName": "Fecha de creación",
    "1034_Description": "Fecha y hora en que se creó el record."
  },
  {
    "FieldSchemaName": "ownerid",
    "1040_DisplayName": "Proprietario",
    "1040_Description": "ID proprietario",
    "1034_DisplayName": "Propietario",
    "1034_Description": "Identificador del propietario."
  }
  // Add more fields as needed...
]

Each object must include:

• FieldSchemaName: The internal name of the attribute.
• DisplayName: The translated label for the attribute.
• Description: A translated description for the attribute.

🔵 If a field matches the FieldSchemaName, its DisplayName and Description will always be overwritten with the provided values instead of being generated by AI.

🔥 Example Workflow

1. Create an Azure OpenAI connection:

pacx ai-translator conn create --name my-openai --deploymentEndpoint https://example.cognitiveservices.azure.com/openai/deployments/gpt-4.1/chat/completions?api-version=2023-12-01-preview --apiKey my-secret-key

2. Generate translation files for a solution:

pacx ai-translator gen --solutionName MySolution --sourceLanguageCode 1033 --targetLanguageCodes 1040 --azureOpenAIConnection my-openai

3. Apply the generated translations:

pacx ai-translator push --translatedExcelPath ./translated-output.xlsx

📋 Requirements

• PACX installed and configured.
• Access to Azure OpenAI services.
• D365/Power Apps environment with proper privileges.

📝 ChangeLog

v1.2.4

• Fixed issues related to the handling the extarction of TwoOptions (Boolean) fields.

v1.2.2

• Renamed alias for --azureOpenAIConnection parameter to -aoac in the gen command

v1.2.1

• Documentation update

v1.2.0

New Features:

• Renamed targetLanguageCode parameter to targetLanguageCodes in the gen command
  The parameter now accepts a comma-separated list of language codes, allowing processing for each requested language.

Breaking Changes:

• The targetLanguageCode parameter is now targetLanguageCodes, which requires providing multiple language codes separated by commas. Existing scripts or commands using the old format will need to be updated.
• The Attribute Translation Contants File structure is changed to support multi-translations process.

v1.1.1

• Bug fix: Fixed the handling of adding the target language code to the Excel file when it is not recognized on the target system.

v1.1.0

New Features:

• Added --exportOriginalOnly parameter to the gen command
  Export only the original translation file without applying any translations.
• Added --force parameter to the gen command
  Force translation even for labels that already contain a translated value. Useful if you want to overwrite existing translations with new ones.
• Added --force parameter to the push command
  Force import of translations even for labels that have not changed from the original. Useful to ensure all target values are updated regardless of differences.

Optimizations:

• Optimized connection storage method (alert: connections will need to be recreated after installing this version)
• For the push command, a translation hashing mechanism has been implemented to identify values that have actually changed compared to the original, ensuring that only modified labels are imported.
  The --force parameter can be used to apply translations while ignoring the hashing check.

v1.0.6

New Features:

• Added support for customizing the batch size of rows sent to Azure OpenAI (--translationsBatchSize)
• Added support for customizing the batch size of translations imported into the target environment (--importBatchSize)

v1.0.5

• Bug fix

v1.0.4

• Bug fix

v1.0.3

• Documentation update

v1.0.2

• Documentation update

v1.0.1

• Documentation update

v1.0.0

• Initial release