Emd.Pacx.Plugins.AITranslator 2.1.0

🌍 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
• Intelligent translation cache that remembers previously translated strings to avoid redundant API calls
• Enhanced AI translation prompt with improved structure and context-aware translations
• Automatic language detection for more accurate translations
• 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)
• Professional tone and terminology consistency for business applications
• Automatically generates and applies localized labels for D365 / Power Apps

🚨 Version 2.1.0 Breaking Changes

Important Notice: Version 2.1.0 introduces breaking changes to parameter aliases for improved usability. If you're upgrading from a previous version, you'll need to update your existing scripts and commands.

Key Changes:

• All parameter aliases have been shortened and standardized for better user experience
• The AI translation prompt has been enhanced for improved translation quality
• Commands remain functionally compatible, only aliases have changed

Please refer to the ChangeLog section for a complete list of parameter alias changes.

⚙️ Installation

Make sure you have PACX installed on your system.

Install the AI Translator plugin with:

pacx tool 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 (-endpoint): [required] Azure OpenAI Deployment Endpoint.
• --apiKey (-key): [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 (-conn): [required] Name of the Azure OpenAI connection.
• --sourceExcelPath (-excel): [optional] Existing Excel file to use instead of fetching from the environment.
• --attributeTranslationConstantsPath (-constants): [optional] Path to a JSON file containing translation constants (for Attributes and Forms).
• --additionalPromptRequestPath (-prompt): [optional] Path to a file containing additional instructions for the AI (e.g., "Always translate 'account' as 'Cliente'").
• --exportFolder (-output): [optional] Path to export the files. Defaults to the current directory.
• --translationsBatchSize (-batch): [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 (-o): [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.

🚀 Performance Optimization: The plugin includes an intelligent cache system that automatically remembers previously translated strings during the same execution. When the same text appears multiple times, it will reuse the cached translation instead of sending it to Azure OpenAI again, significantly improving performance and reducing costs while ensuring translation consistency.

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 (-excel): [required] Path to the Excel file containing translations to apply.
• --importBatchSize (-batch): [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.

📝 Additional Prompt Instructions File

When using the --additionalPromptRequestPath option, you can provide a text file containing custom instructions to guide the AI translation behavior. This is particularly useful for:

• Defining specific terminology translations
• Setting glossary rules
• Providing context-specific translation guidelines
• Maintaining consistency across different translation batches

Example content for the additional prompt file:

Always translate the word "account" as "Cliente" in Italian.
Use formal language for all business-related terms.
When translating field names, prioritize clarity over brevity.
For technical terms like "workflow", keep the English term but add the Italian translation in parentheses: "Workflow (Flusso di lavoro)".

The file should be a plain text file (.txt) containing your custom instructions. The AI will incorporate these instructions along with the base translation prompt to ensure your specific requirements are met.

🔥 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

Or using the shorter aliases:

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

2. Generate translation files for a solution:

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

Or using the shorter aliases:

pacx ai-translator gen -sn MySolution -slc 1033 -tlc 1040 -conn my-openai

With custom prompt instructions:

pacx ai-translator gen -sn MySolution -slc 1033 -tlc 1040 -conn my-openai -prompt ./my-custom-instructions.txt

3. Apply the generated translations:

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

Or using the shorter alias:

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

📋 Requirements

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

🌐 Supported Language Codes

The plugin supports translation for the following language codes:

Usage Examples:

• For Italian translation: --targetLanguageCodes 1040
• For multiple languages: --targetLanguageCodes 1040,1034,1035 (Italian, Spanish, French)
• For English to German: --sourceLanguageCode 1033 --targetLanguageCodes 1031

📝 ChangeLog

v2.1.0

New Features:

• Enhanced AI translation prompt with improved structure and professional tone for better translation quality
• Intelligent translation cache system that stores previously translated strings to improve performance and ensure consistency. The cache automatically reuses translations for repeated text, reducing API calls and costs while maintaining translation consistency across all batches.
• File-based custom prompt instructions with the new --additionalPromptRequestPath parameter, allowing you to store complex, multi-line custom translation instructions in a text file instead of passing them as command-line strings.

Parameter Changes:

• Updated parameter aliases for better consistency:
  • --azureOpenAIConnection: alias changed from -aoac to -conn in the gen command
  • --sourceExcelPath: alias changed from -sep to -excel in the gen command
  • --additionalPromptRequest: REMOVED - replaced with --additionalPromptRequestPath (-prompt) in the gen command
  • --exportFolder: alias changed from -ef to -output in the gen command
  • --translationsBatchSize: alias changed from -tbs to -batch in the gen command
  • --deploymentEndpoint: alias changed from -de to -endpoint in the conn create command
  • --apiKey: alias changed from -ak to -key in the conn create command
  • --translatedExcelPath: alias changed from -tep to -excel in the push command
  • --importBatchSize: alias changed from -ibs to -batch in the push command

Breaking Changes:

• Parameter aliases have been standardized for improved usability. Existing scripts using the old aliases will need to be updated to use the new shorter, more intuitive aliases.
• --additionalPromptRequest parameter has been removed and replaced with --additionalPromptRequestPath (-prompt). Instead of passing custom prompt instructions directly as a string, you now need to create a text file containing your additional instructions and pass the file path. This improves command-line usability and allows for more complex, multi-line custom prompts.

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