Emd.Pacx.Plugins.AITranslator 1.0.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).
• --targetLanguageCode (-tlc): [required] Target language code (e.g., 1040 for Italian).
• --azureOpenAIConnection (-azAICn): [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.

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.

📄 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",
    "DisplayName": "Autore creazione",
    "Description": "Identificatore univoco dell'utente che ha creato il record."
  },
  {
    "FieldSchemaName": "createdon",
    "DisplayName": "Data creazione",
    "Description": "Data e ora in cui il record è stato creato."
  },
  {
    "FieldSchemaName": "ownerid",
    "DisplayName": "Proprietario",
    "Description": "ID proprietario"
  }
  // 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://mydeployment.openai.azure.com/ --apiKey my-secret-key

2. Generate translation files for a solution:

pacx ai-translator gen --solutionName MySolution --sourceLanguageCode 1033 --targetLanguageCode 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.