Core, Doc: Update Azure AI Vision API environment variable names (#119)

2026-08-09 12:00:08 +00:00 · 2025-05-07 22:31:10 +09:00
parent 92b5fd6e3d
commit 58e502303a
33 changed files with 152 additions and 168 deletions
@@ -1,8 +1,8 @@
-# Azure Credentials
-AZURE_SUBSCRIPTION_KEY="your_azure_subscription_key"
-AZURE_AI_SERVICE_ENDPOINT="https://your_azure_ai_service_endpoint"
+# Azure AI Service Credentials (Required for image translation)
+AZURE_AI_SERVICE_API_KEY="your_azure_ai_service_api_key"  # API key from Azure AI Service resource
+AZURE_AI_SERVICE_ENDPOINT="https://your_azure_ai_service_endpoint"  # Endpoint from Azure AI Service resource

-# Azure OpenAI Credentials
+# Azure OpenAI Credentials (Required for text translation)
 AZURE_OPENAI_API_KEY="your_azure_openai_api_key"
 AZURE_OPENAI_ENDPOINT="https://your_azure_openai_endpoint"
 AZURE_OPENAI_MODEL_NAME="your_model_name"
@@ -88,8 +88,16 @@ Co-op Translator takes Markdown files and images from your project folder and pr

 ## Getting Started

+> [!NOTE]
+> While this tutorial focuses on Azure resources, you can use any supported language model from the [supported models and services](#-supported-models-and-services) list.
+
+
 Get started quickly with the CLI or set up full automation with GitHub Actions.

+### Initial Setup
+
+- [Set up Azure AI](./getting_started/set-up-azure-ai.md)
+
 ### Quick Start: Command Line

 For a fast start using the command line:
@@ -128,9 +136,6 @@ Choose the approach that best fits your workflow:
  - [GitHub Actions Guide (Public Repositories & Standard Secrets)](./getting_started/github-actions-guide/github-actions-guide-public.md) - Use this for most public or personal repositories relying on standard repository secrets.
  - [GitHub Actions Guide (Microsoft Organization Repos & Org-Level Setups)](./getting_started/github-actions-guide/github-actions-guide-org.md) - Use this guide if you are working within the Microsoft GitHub organization or need to leverage organization-level secrets or runners.

-> [!NOTE]
-> While this tutorial focuses on Azure resources, you can use any supported language model from the [supported models and services](#-supported-models-and-services) list.
-
 ### Troubleshooting and Tips

 - [Troubleshooting Guide](./getting_started/troubleshooting.md)
@@ -9,17 +9,10 @@
  - For image translation. If unavailable, the translator defaults to [Markdown-only mode](../markdown-only-mode.md).
  - **Azure Computer Vision**

-### Initial Setup
-
-Before you begin, make sure to set up the following resources:
-
- [Set up Azure OpenAI](../set-up-resources/set-up-azure-openai.md)
- [Set up Azure Computer Vision](../set-up-resources/set-up-azure-computer-vision.md) (optional)
-
 ## Table of Contents

 1. [Create an '.env' file in the root directory](./create-env-file.md)
   - Include necessary keys for the chosen language model service.
   - If Azure Computer Vision keys are omitted or `-md` is specified, the translator will operate in Markdown-only mode.
-3. [Install the Co-op translator package](./install-package.md)
-4. [Translate your project using Co-op Translator](./translator-your-project.md)
+1. [Install the Co-op translator package](./install-package.md)
+1. [Translate your project using Co-op Translator](./translator-your-project.md)
@@ -20,13 +20,11 @@ In the root directory of your project, create a file named *.env*. This file wil

 1. Create an *.env* file in the root directory of your project.

-    ![Create *.env* file.](../../imgs/create-env.png)
-
 1. Open the *.env* file and paste the following template:

    ```plaintext
    # Azure Credentials
-    AZURE_SUBSCRIPTION_KEY="your_azure_AIServices_api_key"
+    AZURE_AI_SERVICE_API_KEY="your_azure_ai_service_api_key"
    AZURE_AI_SERVICE_ENDPOINT="https://your_azure_ai_service_endpoint"

    # Azure OpenAI Credentials
@@ -43,51 +41,5 @@ In the root directory of your project, create a file named *.env*. This file wil
    OPENAI_BASE_URL="https://api.openai.com/v1 (If you don't have a custom base URL, you can delete this lin, then it will use the default base URL)"
    ```

-## Gather your Azure credentials
-
-You will need the following Azure credentials on hand to configure the environment:
-
-You can get all the details from the project overview page within [AI Foundry](https://ai.azure.com/build/overview)
-
-![Foundry-overview](../../imgs/foundry-overview.png)
-
-
-### For Azure AI Service:
-
-    - Azure Subscription Key: Your Azure AI Services API Key, which allows you to access the Azure AI services.
-    - Azure AI Service Endpoint: The endpoint URL for your specific Azure AI service.
-
-### For Azure OpenAI Service:
-
-    - Azure OpenAI API Key: The API key for accessing Azure OpenAI services.
-    - Azure OpenAI Endpoint: The endpoint URL for your Azure OpenAI service.
-
-
-1. Copy and paste your AI Services key and Endpoint into the *.env* file.
-2. Copy and paste your Azure OpenAI API Key and Endpoint into the *.env* file.
-
-### Model Details 
-
-Select Model and Endpoints from the left hand menu 
-
-![FoundryModels](../../imgs/gpt-models.png)
-
-You now need to select the model which you wish to utilise to get the model details 
-
-![ModelDetails](../../imgs/model-deployment-name.png)
-
-For the .env file we need the following details 
-
-    - Azure OpenAI Model Name: The name of the model you will be interacting with.
-    - Azure OpenAI Name: The name of your deployment for Azure OpenAI models.
-    - Azure OpenAI API Version: The version of the Azure OpenAI API you are using found at the end of the url string.
-
-To get these details select the model deployment 
-
-![FoundryModelinfo](../../imgs/foundry-model-info.png)
-
-### Add Azure environment variables
-
-3. Copy and paste your Azure OpenAI **Name** and model **Version** into the *.env* file.
-4. Save the *.env* file.
-5. Now, you can access these environment variables to use **Co-op Translator** with your Azure services.
+> [!NOTE]
+> If you want to find your API keys and endpoints, you can refer to [set-up-azure-ai.md](../set-up-azure-ai.md).
@@ -58,17 +58,7 @@ Translating markdown files: 100%|███████████████
 > [!NOTE]
 > While it's generally recommended to translate one language at a time, in situations like this where specific changes need to be added, translating multiple languages at once can be efficient.

-### 3. Specifying the Root Directory
-
-By default, the translator uses the current working directory. If your project is located elsewhere, specify the root directory with the -r option:
-
-```bash
-translate -l "es fr de" -r "./my_project"
-```
-
-This command translates the files in `./my_project` into Spanish, French, and German.
-
-### 4. Updating Translations (Deletes Existing Translations)
+### 3. Updating Translations (Deletes Existing Translations)

 To update existing translations (i.e., delete the current translations and replace them with new ones), use the `-u` option. This will delete all existing translations for the specified languages and re-translate them.

@@ -91,7 +81,7 @@ Translating images: 100%|██████████████████
 Translating markdown files: 100%|███████████████████████████████████| 95/95 [1:40:27<00:00, 125.62s/it]
 ```

-### 6. Translating Only Images
+### 5. Translating Only Images

 To translate only the image files in your project, use the `-img` option:

@@ -101,7 +91,7 @@ translate -l "ko" -img

 This command will translate only the images into Korean, without affecting any markdown files.

-### 7. Translating Only Markdown Files
+### 6. Translating Only Markdown Files

 To translate only the markdown files in your project, use the `-md` option:

@@ -109,7 +99,7 @@ To translate only the markdown files in your project, use the `-md` option:
 translate -l "ko" -md
 ```

-### 8. Checking for Errors in Translated Files
+### 7. Checking for Errors in Translated Files

 If you want to check translated files for errors and retry the translation if necessary, use the `-chk` option:

@@ -136,7 +126,7 @@ For example, this method is useful for detecting missing chunks or corrupted tra

 However, if you already know which files are problematic, it’s more efficient to manually delete those files and use the `-a` option to re-translate them.

-### 9. Debug Mode
+### 8. Debug Mode

 To enable detailed logging for troubleshooting, use the `-d` option:

@@ -156,7 +146,7 @@ DEBUG:openai._base_client:Request options: {'method': 'post', 'url': '/chat/comp
 ...
 ```

-### 10. Translating All Languages
+### 9. Translating All Languages

 If you want to translate the project into all supported languages, use the all keyword.

@@ -171,8 +161,10 @@ This command will translate the project into all available languages. If you pro

 > [!TIP]
 >
-> ### Deleting files which need to be updated 
-> To update files recently changed in Pull Request the first step is to delete all the existing versions of the specific file located in the different language translation folders. You can do this in bulk by using the following command to delete all the files with a specific name within the translation folders.
+> ### Manually Deleting Translated Files (Optional)
+> Translated files are now automatically detected and cleaned up when a source file is updated.
+>
+> However, if you want to manually update a translation - for example, to redo a specific file or override the system behavior - you can use the following command to delete all versions of the file across language folders.
 >
 > ### On Windows:
 > 1. **Using Command Prompt**:
@@ -204,4 +196,4 @@ This command will translate the project into all available languages. If you pro
 >
 > Always double-check the files before deleting to avoid accidental loss. 
 >
-> Once you have deleted the files which need to be replace simply rerun your `translate -l` command to update the most recent file changes.
+> Once you have deleted the files which need to be replace simply rerun your `translate -l` command to update the most recent file changes.
@@ -21,14 +21,12 @@ You need credentials for at least one supported Language Model:
 - **Azure OpenAI**: Requires Endpoint, API Key, Model/Deployment Names, API Version.
 - **OpenAI**: Requires API Key, (Optional: Org ID, Base URL, Model ID).
 - See [Supported Models and Services](../../README.md/#-supported-models-and-services) for details.
- Setup Guide: [Set up Azure OpenAI](../set-up-resources/set-up-azure-openai.md).

-**2. Optional: Computer Vision Credentials (for Image Translation)**
+**2. Optional: AI Vision Credentials (for Image Translation)**

 - Required only if you need to translate text within images.
- **Azure Computer Vision**: Requires Endpoint and Subscription Key.
+- **Azure AI Vision**: Requires Endpoint and Subscription Key.
 - If not provided, the action defaults to [Markdown-only mode](../markdown-only-mode.md).
- Setup Guide: [Set up Azure Computer Vision](../set-up-resources/set-up-azure-computer-vision.md).

 ## Setup and Configuration

@@ -0,0 +1,105 @@
+# Set Up Azure AI for Co-op Translator (Azure OpneAI & Azure AI Vision)
+
+This guide walks you through setting up Azure OpenAI for language translation and Azure Computer Vision for image content analysis (which can then be used for image-based translation) within Azure AI Foundry.
+
+**Prerequisites:**
+- An Azure account with an active subscription.
+- Sufficient permissions to create resources and deployments in your Azure subscription.
+
+## Create an Azure AI Project
+
+You'll start by creating an Azure AI Project, which acts as a central place for managing your AI resources.
+
+1. Navigate to [https://ai.azure.com](https://ai.azure.com) and sign in with your Azure account.
+
+1. Select **+Create** to create a new project.
+
+1. Perform the following tasks:
+   - Enter a **Project name** (e.g., `CoopTranslator-Project`).
+   - Select the **AI hub**  (e.g., `CoopTranslator-Hub`) (Create a new one if needed).
+
+1. Click "**Review and Create**" to set up your project. You will be taken to your project's overview page.
+
+## Set up Azure OpenAI for Language Translation
+
+Within your project, you will deploy an Azure OpenAI model to serve as the backend for text translation.
+
+### Navigate to Your Project
+
+If not already there, open your newly created project (e.g., `CoopTranslator-Project`) in Azure AI Foundry.
+
+### Deploy an OpenAI Model
+
+1. From your project's left-hand menu, under "My assets", select "**Models + endpoints**".
+
+1. Select **+ Deploy model**.
+
+1. Select **Deploy Base Model**.
+
+1. You will be presented with a list of available models. Filter or search for a suitable GPT model. We recommend `gpt-4o`.
+
+1. Select your desired model and click **Confirm**.
+
+1. Select **Deploy**.
+
+### Azure OpenAI configuration
+
+Once deployed, you can select the deployment from the "**Models + endpoints**" page to find its **REST endpoint URL**, **Key**, **Deployment name**, **Model name** and **API version**. These will be needed to integrate the translation model into your application.
+
+## Set up Azure Computer Vision for Image Translation
+
+To enable translation of text within images, you need to find the Azure AI Service API Key and Endpoint.
+
+1. Navigate to your Azure AI Project (e.g., `CoopTranslator-Project`). Ensure you are in the project overview page.
+
+### Azure AI Service configuration
+
+Find the API Key and Endpoint from the Azure AI Service.
+
+1. Navigate to your Azure AI Project (e.g., `CoopTranslator-Project`). Ensure you are in the project overview page.
+
+1. Find the **API Key** and **Endpoint** from the Azure AI Service tab.
+
+    ![Find API Key and Endpoint](./imgs/find-azure-ai-info.png)
+
+This connection makes the capabilities of the linked Azure AI Services resource (including image analysis) available to your AI Foundry project. You can then use this connection in your notebooks or applications to extract text from images, which can subsequently be sent to the Azure OpenAI model for translation.
+
+## Consolidating Your Credentials
+
+By now, you should have collected the following:
+
+**For Azure OpenAI (Text Translation):**
+- Azure OpenAI Endpoint
+- Azure OpenAI API Key
+- Azure OpenAI Model Name (e.g., `gpt-4o`)
+- Azure OpenAI Deployment Name (e.g., `cooptranslator-gpt4o`)
+- Azure OpenAI API Version
+
+**For Azure AI Services (Image Text Extraction via Vision):**
+- Azure AI Service Endpoint
+- Azure AI Service API Key
+
+### Example: Environment Variable Configuration (Preview)
+
+Later, when building your application, you'll likely configure it using these collected credentials. For instance, you might set them as environment variables like so:
+
+```bash
+# Azure AI Service Credentials (Required for image translation)
+AZURE_AI_SERVICE_API_KEY="your_azure_ai_service_api_key" # e.g., 21xasd...
+AZURE_AI_SERVICE_ENDPOINT="https://your_azure_ai_service_endpoint.cognitiveservices.azure.com/"
+
+# Azure OpenAI Credentials (Required for text translation)
+AZURE_OPENAI_API_KEY="your_azure_openai_api_key" # e.g., 21xasd...
+AZURE_OPENAI_ENDPOINT="https://your_azure_openai_endpoint.openai.azure.com/"
+AZURE_OPENAI_MODEL_NAME="your_model_name" # e.g., gpt-4o
+AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="your_deployment_name" # e.g., cooptranslator-gpt4o
+AZURE_OPENAI_API_VERSION="your_api_version" # e.g., 2024-02-01
+```
+
+---
+
+### Further Reading
+
+- [How to Create a project in Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/how-to/create-projects?tabs=ai-studio)
+- [How to Create Azure AI resources](https://learn.microsoft.com/azure/ai-foundry/how-to/create-azure-ai-resource?tabs=portal)
+- [How to Deploy OpenAI models in Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai)
@@ -1,20 +0,0 @@
-# Set up Azure Computer Vision for image translation
-
-### Create an Azure AI Services using Microsoft AI Foundry
-
-To create AI Services computer vision services with AI Foundry, follow these steps:
-
-1. **Sign in to the Azure AI Foundry portal**: Make sure you have an Azure account with the necessary permissions.
-2. **Create a new project**: Go to the "Projects" section and click on "Create a project." Follow the prompts to set up your project.
-3. **Connect to Azure AI Services**: In your project, go to the "Management center" and select "Connected resources." Click on "+ New connection" and choose the AI service you want to connect.
-
-![Foundry-resources](../../imgs/foundry-resources.png)
-
-4. **Select Computer Vision**: Choose the Computer Vision service from the list of available AI services.
-5. **Configure the service**: Follow the instructions to configure the Computer Vision service according to your needs.
-6. **Deploy the service**: Once configured, deploy the service to start using it in your project.
-
-For more detailed instructions, you can refer to the official documentation. 
-
-[Azure AI Foundry documentation](https://learn.microsoft.com/azure/ai-studio/ai-services/how-to/connect-ai-services).
-
@@ -1,48 +0,0 @@
-# Set up Azure OpenAI for language translation
-
-## Create an Azure OpenAI resource in Azure AI Foundry
-
-To set up Azure OpenAI in Azure AI Foundry, follow these steps:
-
-### Creating a Hub
-
-1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com): Make sure you're signed in with your Azure account.
-
-2. Navigate to the Management Center: From the home page, select "Management Center" from the left menu.
-
-3. Create a New Hub: Click on "+ New hub" and enter the necessary details such as Subscription, Resource Group, and Hub Name, we recomend deploying the hub to East US as this region support Cognitive vision and GPT models.
-
-4. Review and Create: Review the details and click "Create" to set up your hub.
-
-### Creating a Project
-
-1. Go to the Home Page: If you're not already there, select "Azure AI Foundry" at the top left of the page to go to the home page.
-
-2. Create a Project: Click on "+ Create project" and enter a name for your project.
-
-3. Select a Hub: If you have multiple hubs, select the one you want to use. If you want to create a new hub, you can do so during this step3.
-
-4. Configure the Project: Follow the prompts to configure your project according to your needs.
-
-5. Create the Project: Click "Create" to finalize the setup.
-
-### Deploying a Model and Endpoint for OpenAI model
-
-1. Sign in to the [Azure AI Foundry portal](https://ai.azure.com): Make sure you're signed in with the Azure subscription that has your Azure OpenAI Service resource.
-
-2.Navigate to Models and Endpount: From the Azure AI Foundry home page, find the tile that says " and select "Let's go." or Model and Endpoints in the left hand menu.
-
-3. If you dont already have a GPT Model deployed select deploy model: select a GPT model we recommend GPT-4o, GPT-4o-mini or o3-mini 
-
-4. Access your resources: You should see your existing Azure OpenAI Service resources. If you have multiple resources, use the selector to choose the one you want to work with.
-
-
-For more detailed instructions, you can refer to the official Azure AI Foundry documentation.
-
-[How to Create a project](https://learn.microsoft.com/azure/ai-studio/how-to/create-project)
-
-[How to Create resources](https://learn.microsoft.com/azure/ai-studio/how-to/create-azure-ai-resource)
-
-[How to use OpenAI Model in AI Foundry](https://learn.microsoft.com/azure/ai-studio/ai-services/how-to/connect-azure-openai)
-
-[OpenAI Services in Azure AI Foundry](https://learn.microsoft.com/azure/ai-studio/azure-openai-in-ai-studio)
@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "co_op_translator"
-version = "0.8.5"
-description = "Easily automate multilingual translations for your projects with co-op-translator, powered by advanced LLM technology."
+version = "0.8.6"
+description = "Easily automate the translation of your documentation into multiple languages to reach a global audience."
 authors = [
    "Minseok Song <skytin1004@gmail.com>",
    "timothychungd <timothychungd@gmail.com>"
@@ -5,8 +5,18 @@ class AzureComputerVisionConfig:
    """Azure Computer Vision specific configuration."""

    @staticmethod
-    def get_subscription_key():
-        """Retrieve the Azure subscription key from environment variables."""
+    def get_api_key():
+        """Retrieve the Azure AI Vision API key from environment variables.
+
+        First checks for AZURE_AI_SERVICE_API_KEY (recommended), then falls back to
+        AZURE_SUBSCRIPTION_KEY for backward compatibility.
+        """
+        # First check new naming convention (Azure AI Vision)
+        key = os.getenv("AZURE_AI_SERVICE_API_KEY")
+        if key:
+            return key
+
+        # Fall back to legacy naming convention for backward compatibility
        return os.getenv("AZURE_SUBSCRIPTION_KEY")

    @staticmethod
@@ -53,16 +53,13 @@ class VisionConfig:
        if provider == VisionProvider.AZURE_COMPUTER_VISION:
            azure_config = AzureComputerVisionConfig()
            # If any required environment variable is missing, return None
-            if (
-                not azure_config.get_subscription_key()
-                or not azure_config.get_endpoint()
-            ):
+            if not azure_config.get_api_key() or not azure_config.get_endpoint():
                return None

            return VisionServiceConfig(
                required=True,
                env_vars={
-                    "AZURE_SUBSCRIPTION_KEY": azure_config.get_subscription_key(),
+                    "AZURE_AI_SERVICE_API_KEY": azure_config.get_api_key(),
                    "AZURE_AI_SERVICE_ENDPOINT": azure_config.get_endpoint(),
                },
            )
@@ -25,5 +25,5 @@ class AzureImageTranslator(ImageTranslator):
            ImageAnalysisClient: The initialized client.
        """
        endpoint = AzureComputerVisionConfig.get_endpoint()
-        subscription_key = AzureComputerVisionConfig.get_subscription_key()
+        subscription_key = AzureComputerVisionConfig.get_api_key()
        return ImageAnalysisClient(endpoint, AzureKeyCredential(subscription_key))