{"id":28367206,"url":"https://github.com/tolgee/ai-migrator","last_synced_at":"2026-03-16T06:34:35.179Z","repository":{"id":258219565,"uuid":"867522693","full_name":"tolgee/ai-migrator","owner":"tolgee","description":"A tool for migrating projects with hard-coded strings to Tolgee JS","archived":false,"fork":false,"pushed_at":"2024-11-14T09:42:46.000Z","size":404,"stargazers_count":20,"open_issues_count":2,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-09-20T03:18:55.288Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tolgee.png","metadata":{"files":{"readme":"README.backup.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["tolgee"]}},"created_at":"2024-10-04T08:19:24.000Z","updated_at":"2024-12-05T07:02:54.000Z","dependencies_parsed_at":"2024-11-14T18:17:06.473Z","dependency_job_id":null,"html_url":"https://github.com/tolgee/ai-migrator","commit_stats":null,"previous_names":["tolgee/ai-migrator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tolgee/ai-migrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Fai-migrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Fai-migrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Fai-migrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Fai-migrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tolgee","download_url":"https://codeload.github.com/tolgee/ai-migrator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolgee%2Fai-migrator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30570772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-16T06:02:37.763Z","status":"ssl_error","status_checked_at":"2026-03-16T06:02:14.913Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-29T01:08:43.269Z","updated_at":"2026-03-16T06:34:35.164Z","avatar_url":"https://github.com/tolgee.png","language":"TypeScript","funding_links":["https://github.com/sponsors/tolgee"],"categories":[],"sub_categories":[],"readme":"# AI Migration Tool\n\n_Disclaimer: This tool is not released yet! It's in PoC state. Use at your own risk._\n\nThis tool automates the process of migrating string literals in TypeScript and TSX files to localized keys using ChatGPT, compatible with both Azure OpenAI and OpenAI setups, and Tolgee. It tracks the migration status of each file, preventing duplicate processing, and uploads\nlocalization keys to Tolgee for translation management.\n\n### Features\n\n- **File Discovery:** Finds `.tsx` files in your project directory based on a specified pattern.\n- **ChatGPT Localization:** Uses ChatGPT, compatible with both Azure OpenAI and OpenAI setups, to replace string literals in React components with Tolgee's `\u003cT\u003e`\n  component or `useTranslate` hook.\n- **Migration Status Tracking:** Saves and loads the migration status from a JSON file, ensuring that files are\n  processed only once.\n- **Tolgee Integration:** Uploads the created localization keys to the Tolgee platform via its REST API.\n\n\u003chr\u003e\n\n### Table of Contents\n\n- [Installation](#installation)\n- [Environment Variables](#environment-variables)\n- [Usage](#usage)\n  - [CLI Commands](#cli-commands)\n- [Modules](#modules)\n  - [File Finder](#1-file-finder-findfilests)\n  - [Migration Status](#2-migration-status-migrationStatusts)\n  - [ChatGPT Localization](#3-chatgpt-localization-chatgptts)\n  - [Tolgee Integration](#4-tolgee-integration-tolgeets)\n- [Testing](#testing)\n- [Error Handling](#error-handling)\n- [Conclusion](#conclusion)\n\n\u003chr\u003e\n\n### Installation\n\n#### Option 1: Run Directly with `npx`\n\nIf you prefer not to install the tool globally, you can run it directly using `npx`:\n\n```bash\nnpx tolgee-migrator migrate [options]\n```\n\n#### Option 2: Clone and Install Locally\n\n1. **Clone the repository:**\n\n   ```bash\n   git clone https://github.com/tolgee/ai-migrator\n   cd ai-migrator\n   ```\n\n2. **Install the dependencies:**\n\n   ```bash\n   npm install\n   ```\n\n3. **Build the project:** This project is written in TypeScript, so you need to compile it to JavaScript before running\n   the\n   commands:\n   ```bash\n   npm run build\n   ```\n4. **Rebuild after changes:** Whenever you make changes to the TypeScript files, you need to rebuild the project by\n   running:\n   ```bash\n   npm run build\n   ```\n5. **Run the tool:** After building the project, you can use the CLI as described in the [Usage](#usage) section.\n\n\u003chr\u003e\n\n### API Key and Endpoint Configuration\n\nTo configure the tool, provide either Azure OpenAI or OpenAI credentials through command-line arguments based on the setup you're using.\n\n**For Azure OpenAI:**\n\n- `--azure-api-key`: The API key for Azure OpenAI, required for interacting with the ChatGPT API.\n- `--azure-endpoint`: The endpoint URL for your Azure OpenAI instance, used to send API requests to Azure OpenAI.\n\n**For OpenAI:**\n\n- `--openai-api-key`: The API key for OpenAI, required for accessing OpenAI’s ChatGPT API.\n\nFor example, when running a migration, pass these arguments to set the configuration:\n\n```bash\ntolgee-migrator migrate --openai-api-key \u003cyour-openai-api-key\u003e\n```\n\nOr, if using Azure OpenAI:\n\n```bash\ntolgee-migrator migrate --azure-api-key \u003cyour-azure-api-key\u003e --azure-endpoint \u003cyour-azure-endpoint\u003e\n```\n\n\u003chr\u003e\n\n### Usage\n\n#### CLI Commands\n\nThe AI Migration Tool provides a command-line interface for migrating string literals to localization keys and uploading\nthem to Tolgee.\n\n**Command:** `migrate`\n\nThe `migrate` command processes `.tsx` files in the project directory, replaces\nstring literals with Tolgee’s `\u003cT\u003e` component or `useTranslate` hook, and generates an `allKeys.json` file containing the created localization keys.\n\n**Process Overview:**\n\n1.  The project files are overwritten with new components.\n2.  An `allKeys.json` file is generated and stored in the root of the project, containing the keys for localization.\n3.  Users can then manually review or modify both the project files and the `allKeys.json` file.\n\n**Usage**\n\n```bash\ntolgee-migrator migrate [options]\n```\n\n**Options**\n\n- `-l, --log-level \u003clevel\u003e`: Sets the logging level. Available options are `error`, `warn`, `info`, `verbose`, and `debug`. Defaults to `info.\n\n  - Example:\n\n    ```bash\n    tolgee-migrator --log-level debug migrate --pattern \"src/test_files/**/*.tsx\"\n    ```\n\n- `-p, --pattern \u003cpattern\u003e`: Defines the file pattern to search for files to process. The default pattern is `src/**/*.tsx`.\n\n  - Example:\n\n    ```bash\n    tolgee-migrator migrate --pattern \"src/test_files/**/*.tsx\"\n    ```\n\n- `-u, --upload`: Automatically uploads the created localization keys to Tolgee. If this option is **not** provided, you can upload the keys manually in a separate step using the `upload-keys` command.\n\n  - Example:\n\n    ```bash\n    tolgee-migrator migrate --upload\n    ```\n\n- `-a, --appendixPath \u003cappendixPath\u003e`: Specifies the path to a file containing custom instructions (prompt appendix) for ChatGPT. This allows you to provide additional context or guidelines for the migration process.\n\n  - Example:\n\n    ````bash\n    tolgee-migrator migrate --appendixPath \"./path/to/instructions.txt\"\n    ```- `--azure-api-key \u003cazureApiKey\u003e`: Specifies the Azure OpenAI API key.\n    ````\n\n- `--azure-endpoint \u003cazureEndpoint\u003e`: Specifies the Azure OpenAI endpoint URL.\n\n- `--openai-api-key \u003copenAiApiKey\u003e`: Specifies the OpenAI API key.\n\n**Examples:**\n\n- Run the migration with the default file pattern and review the `allKeys.json` file before uploading:\n\n  ```bash\n  tolgee-migrator migrate\n  ```\n\n- Run the migration for files in the `src/test_files/` directory and automatically upload the keys:\n\n  ```bash\n  tolgee-migrator migrate --pattern \"src/test_files/**/*.tsx\" --upload\n  ```\n\n- Run the migration with a custom prompt appendix for ChatGPT, using the default file pattern:\n\n  ```bash\n  tolgee-migrator migrate --appendixPath \"./path/to/instructions.txt\"\n  ```\n\n- Run the migration with a specific file pattern, automatically upload the keys, and use a custom prompt appendix:\n\n  ```bash\n  tolgee-migrator migrate --pattern \"src/test_files/**/*.tsx\" --upload --appendixPath \"./path/to/instructions.txt\"\n  ```\n\n\u003cbr\u003e\n\n**Command:** `upload-keys`\n\nThe `upload-keys` command allows you to upload the localization keys that were generated and stored in the `allKeys.json` file to the Tolgee platform. This command is run after reviewing and updating the `allKeys.json` file or project files as needed.\n\n**Process Overview:**\n\n1.  Users **review and modify** the `allKeys.json` file and project files.\n2.  Once ready, run the upload-keys` command to upload the finalized localization strings to the Tolgee platform.\n\n**Usage**\n\n```bash\ntolgee-migrator upload-keys\n```\n\n**Examples:**\n\n- Upload keys from `allKeys.json` to Tolgee after reviewing and finalizing them:\n\n  ```bash\n  tolgee-migrator upload-keys\n  ```\n\n\u003cbr\u003e\n\n**Command:** `status`\n\nThe `status` command allows you to check the migration status of a specific file or view the entire migration status.\n\n**Usage**\n\n```bash\ntolgee-migrator status [file] [options]\n```\n\n**Options**\n\n- `[file]`: Specify a file path to check the migration status for that particular file.\n\n  - Example:\n\n    ```bash\n    tolgee-migrator status src/test_files/App.tsx\n    ```\n\n- `--all`: Show the entire migration status for all processed files.\n\n  - Example:\n\n    ```bash\n    tolgee-migrator status --all\n    ```\n\n**Examples:**\n\n- Check the migration status for a specific file:\n\n  ```bash\n  tolgee-migrator status src/test_files/App.tsx\n  ```\n\n- Show the entire migration status:\n\n  ```bash\n  tolgee-migrator status --all\n  ```\n\n\u003chr\u003e\n\n**Verbose Logging with Log Levels**\n\nThe `tolgee-migrator` CLI supports multiple logging levels to control output verbosity.\n\n- **Default Level (info)**: Displays important messages and errors only. Shows a progress bar indicating the number of files processed.\n- **Verbose**: Displays additional information about each file currently being handled.\n- **Debug**: Logs detailed information including full prompts and responses from ChatGPT for each file.\n\nTo set the log level, use the `-l` or `--log-level` option:\n\n```bash\ntolgee-migrator migrate --log-level debug\n```\n\nThe available log levels are:\n\n- `error`: Only error messages.\n- `warn`: Warning and error messages.\n- `info`: Important messages, errors, and progress updates (default).\n- `verbose`: Information about each file being processed.\n- `debug`: Full output, including prompts and responses.\n\n\u003chr\u003e\n\n**Running the CLI**\n\nYou can run the CLI directly using npx without global installation:\n\n```bash\nnpx tolgee-migrator migrate\n```\n\nOr, for a more convenient setup, you can link the package globally using:\n\n```bash\nnpm link\n```\n\nAfter linking, you can run the CLI globally:\n\n```bash\ntolgee-migrator migrate\n```\n\n\u003chr\u003e\n\n### Complete Workflow Example\n\n1.  **Step 1:** Run the migration to process the files , generate `allKeys.json`, and set the log level to `debug` to see all output.\n\n    ```bash\n    tolgee-migrator migrate --pattern \"src/test_files/**/*.tsx\" --log-level debug --openai-api-key \u003cyour-openai-api-key\u003e\n    ```\n\n2.  **Step 2:** Open the project files and `allKeys.json`, review and make any necessary updates or changes.\n\n3.  **Step 3:** Once satisfied with the changes, upload the keys to the Tolgee platform:\n\n    ```bash\n    tolgee-migrator upload-keys\n    ```\n\n\u003chr\u003e\n\n### Modules\n\n### 1. File Finder (`findFiles.ts`)\n\nThis module uses `fast-glob` to find all files in the project directory based on a provided pattern. It\nreturns a list of file paths that match the pattern.\n\n#### Example Usage:\n\n```ts\nimport { findFiles } from \"./findFiles\";\n\nconst files = await findFiles(\"src/**/*.tsx\");\nconsole.log(\"Files found:\", files);\n```\n\n### 2. Migration Status (`migrationStatus.ts`)\n\nThis module manages the migration status, saving, loading, and checking it from a JSON file (migration-status.json). The\nstatus is used to track which files have already been processed, ensuring that each file is processed only once.\n\n- **updateMigrationStatus:** Saves the current migration status to a JSON file.\n- **loadMigrationStatus:** Loads the migration status from the JSON file, creating the file if it doesn't exist.\n- **checkMigrationStatus:** Checks the migration status of a specific file or displays the entire migration status if\n  requested.\n\n#### Example Usage:\n\n```ts\nimport {\n  loadMigrationStatus,\n  updateMigrationStatus,\n  checkMigrationStatus,\n} from \"./migrationStatus\";\n\n// Load the migration status\nconst status = await loadMigrationStatus();\nconsole.log(\"Migration Status:\", status);\n\n// After processing a file, update the status\nawait updateMigrationStatus(\"src/test_files/App.tsx\", [\"keyName1\", \"keyName2\"]);\n\n// Check the status of a specific file\nawait checkMigrationStatus(\"src/test_files/App.tsx\");\n\n// Show the entire status\nawait checkMigrationStatus(\"\", true);\n```\n\n### 3. ChatGPT Localization (`chatGPT.ts`)\n\nThis module communicates with ChatGPT, using either Azure OpenAI or OpenAI setup, to process `.tsx` file contents, primarily for React components. It sends the content of `.tsx` files\nto ChatGPT, requesting that string literals be replaced with the Tolgee `\u003cT\u003e` component or `useTranslate` hook. The\nfunction returns the updated file content and the list of created localization keys.\n\n#### Example Usage:\n\n```ts\nimport { sendFileToChatGPT } from \"./chatGPT\";\n\nconst result = await sendFileToChatGPT(\"src/test_files/App.tsx\");\nconst { updatedContent, createdKeys } = result;\n\nconsole.log(\"Updated Content:\", updatedContent);\nconsole.log(\"Created Keys:\", createdKeys);\n```\n\n#### Extracting Keys\n\nThe `extractCreatedKeys` function parses the response from ChatGPT, using either Azure OpenAI or OpenAI setup, to extract localization keys,\ndescriptions, and translations. This allows for more robust handling of the response structure and ensures that the\ncorrect format is returned. The key names, descriptions, and default values are returned as part of the final\nlocalization setup.\n\n\u003chr\u003e\n\n### 4. Tolgee Integration (`uploadKeysToTolgee.ts`)\n\nThis module is responsible for uploading the keys from the `allKeys.json` file to the Tolgee platform. You can run this step manually after the migration process to ensure that all keys are finalized before uploading.\n\n#### Example Usage:\n\n```ts\nimport { uploadKeysToTolgee } from \"./uploadKeysToTolgee\";\n\nconst keys = [\n  {\n    keyName: \"menu.item.translation\",\n    description: \"Menu item translation\",\n    translations: { en: \"Translation\" },\n  },\n];\n\nconst result = await uploadKeysToTolgee(keys);\nif (result.success) {\n  console.log(result.message); // Logs: Keys uploaded successfully\n} else {\n  console.error(result.message); // Logs error message if upload fails\n}\n```\n\n\u003chr\u003e\n\n### Testing\n\nThis project includes unit tests to ensure the functionality of each module, such as file discovery, migration status tracking, and Tolgee API integration. We use [Jest](https://jestjs.io/) as the testing framework.\n\n#### Running Tests\n\nTo run all tests, use the following command:\n\n```bash\nnpm test\n```\n\nYou can also run specific test files:\n\n```\nnpm test tests/migrationStatus.test.ts\n```\n\n\u003chr\u003e\n\n### Error Handling\n\nEach module includes error handling for improved reliability:\n\n- **File Finder:** Catches errors while reading the file system and throws meaningful messages.\n- **Migration Status:** Logs errors if the migration status file cannot be read or written to.\n- **ChatGPT Localization:** Throws errors when there is a failure during the ChatGPT API call.\n- **Tolgee Integration:** Handles and logs errors that occur during the key upload process.\n- **CLI Feedback:** The CLI informs the user about any files that fail to process or upload. Error messages will be\n  displayed directly in the CLI output, including details about which step failed (e.g., file reading, localization, key\n  upload).\n\n### Conclusion\n\nThis tool automates the migration of string literals in TypeScript/TSX files to localized keys using ChatGPT, through either Azure OpenAI or OpenAI setup, and Tolgee. It is designed for ease of use, tracking migration status to prevent duplicate processing, and integration\nwith the Tolgee platform for seamless localization management.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolgee%2Fai-migrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftolgee%2Fai-migrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolgee%2Fai-migrator/lists"}