Automating Technical Blog Localization with Gemini CLI Agent Skills [GDE]

The Use Case: Scaling Content to Global Tech Communities

When content writers write English blog posts, they often want to distribute them to different tech communities to share knowledge, increase impact, and reach. However, many readers in these communities do not read, write, or speak English. When the blog post is posted in these localized, language-specific Facebook Groups, their followers do not read it and miss out on valuable insights.

I often write English blog posts for global tech communities, but I encountered an obstacle when sharing them in localized groups, like Taiwan's Traditional Chinese Facebook communities. My readers there missed out because of the language barrier, and I lacked the technical vocabulary to translate them manually. My solution? I built a custom Agent Skill for the Gemini CLI.

The skill identifies the target language in the user prompt and loads the terminology files from the target language folder to perform the translation. Then, the skill runs a Node.js script to verify that the source and target URLs match and that the Alt-text and link text have been translated to improve accessibility and boost SEO.

This guide demonstrates how to build the translation agent skill for the Gemini CLI.

Prerequisites

Before we begin, ensure you have the following:

• Install the gemini-cli.
• Generate a Google AI Studio API Key or a Vertex AI Credential.
• Ensure you have access to a terminal (macOS, Linux, or WSL).
• Install Node.js v18+ to run the script.

Setting Up the Environment

Install the Gemini CLI globally.

npm install -g @google/gemini-cli

To access your extension and the API key globally, create a .env file in the ~/.gemini global workspace, and add the API key to the .env file as follows:

# Your Google AI Studio API Key
GEMINI_API_KEY=<Gemini API Key>

We use the ~/.gemini path, which is standard for macOS/Linux systems. This guide assumes familiarity with a Unix-like environment. Windows (PowerShell/CMD) users might need to adjust paths or commands slightly.

Gemini CLI automatically loads variables from the first .env file it finds, searching up from the current directory, then in ~/.gemini/.env or ~/.env.

When the CLI loads the GEMINI_API_KEY from the .gemini/.env file, it works in projects automatically. Moreover, it acts as a single source of truth for key rotation. When the key expires, users only need to update a single file, rather than locating multiple copies scattered across projects.

Source Code

The full source code for this skill is available in the Technical Localization Expert Agent Skill, however, the following section examines how the key components work.

The Architecture: Orchestrating a Translation Agent Skill

1. A user enters a prompt in the Gemini CLI to use the technical-localization-expert skill to translate an English blog to Traditional Chinese.

2. The CLI activates the skill, loads the Taiwanese technical terminology files from the references folder.

3. The skill directs the CLI to execute the Linux cat command to read the source blog post.

4. The skill builds a terminology mapping and injects it, along with the source text, into the translation prompt context to generate the translated text.

5. The Node.js link validation script in the scripts folder validates the links of the translated text are valid.

6. The skill saves the translated text to a markdown file in the chinese-blogs folder.

7. The audit report lists the localization process's steps and each step produces the expected outcome.

Structure of an Agent Skill

An Agent Skill is a self-contained directory with a required SKILL.md Markdown file, and optional folders such as scripts, references, and assets. When the directory is placed in the skills folder of the global .gemini folder, it is available after restart.

my-skill/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

In our translate blog post skill, the top folder name (my-skill) is named technical-localization-expert to match the skill name to avoid confusion and facilitate discovery.

The references folder contains terminology files grouped under terminology-en-[code] subfolders where [code] is the target language code. The markdown file has a mapping table to map the English terms to the target language. For example, this table maps common AI terms from English to Traditional Chinese.

# AI

| English | zh-TW (Taiwan Standard) | Notes |
| :--- | :--- | :--- |
| Artificial Intelligence | 人工智慧 | Never use 人工智能 |
| Training | 訓練 | |
| Inference | 推論 | Not 推理 |
| Fine-tuning | 微調 | |
| Model | 模型 | |
| Hyperparameter | 超參數 | |
| Prompt | 提示詞 | |
| Embedding | 嵌入 | |
| Large Language Model | 大型語言模型 | LLM |

Finally, the scripts folder contains a Node.js script to perform validations on the assets and links in the translated text.

Let's create the folder structure of the agent skill.

Create a Basic Agent Skill

The following commands create all the folders and empty files for the translate blog post skill.

cd ~    # Switch to the home directory
mkdir technical-localization-expert
touch SKILL.md

# Create the references folder, subfolder, and terminology files
mkdir technical-localization-expert/references
mkdir technical-localization-expert/references/terminology-en-zhtw

mkdir technical-localization-expert/references/terminology-en-zhtw/ai.md
mkdir technical-localization-expert/references/terminology-en-zhtw/backend.md
mkdir technical-localization-expert/references/terminology-en-zhtw/cloud.md
mkdir technical-localization-expert/references/terminology-en-zhtw/frontend.md
mkdir technical-localization-expert/references/terminology-en-zhtw/general.md
mkdir technical-localization-expert/references/terminology-en-zhtw/internet.md

# Create the scripts folder and an empty Node.js file
mkdir technical-localization-expert/scripts
touch technical-localization-expert/scripts/check-links.js

The following section analyzes each component of the skill in detail.

The Reference Files

For maintainability and scalability, the files are placed under terminology-en-zhtw for Traditional Chinese. The terminology-en-zhtw directory contains ai.md, frontend.md, backend.md, web.md, cloud.md, general.md, and internet.md Markdown files to keep the standard Taiwan terminology.

Extend this modular design to Simplified Chinese by simply adding a terminology-en-zhcn folder. This ensures the agent uses correct regional terms, such as 軟件 (Simplified) instead of 軟體 (Traditional).

We can find the markdown files in terminology-en-zhtw and copy the markdown tables to our empty files.

After the CLI activates the skill, it loads these files to build a single map of English-to-Traditional-Chinese technical terms. Moreover, it injects the map and the source blog post into the user prompt to generate the translated Traditional Chinese blog post and saves it to a destination folder.

The validation script verifies URLs, Alt-text, and links before we finalize the post for publication.

Automated Asset Validation (The Node.js Script)

The check-links.js script validates the original and translated blog posts. While Gemini is powerful, LLMs can occasionally hallucinate URLs or accidentally translate technical paths. This script provides a deterministic check to ensure the blog remains functional.

First, the script ensures the Alt-text and link texts are translated to improve accessibility.

assetRegex is a regular expression to match the images with Alt-text and URLs with link text. The extract function extracts the assets to verify the texts are not translated by accident.

const assetRegex = /(!?)\[([^\]]*)\]\(([^)]+)\)/g;

const extract = (content) => {
  const results = [];
  let match;
  while ((match = assetRegex.exec(content)) !== null) {
    results.push({
      isImage: match[1] === '!',
      text: match[2].trim(),
      url: match[3].trim()
    });
  }
  return results;
};

const sourceAssets = extract(sourceContent);
const targetAssets = extract(targetContent);

When the text is neither in a single-backtick block nor a triple-backticks block, the source and target texts should not be the same. If they are the same, an error occurs, and an error message is pushed to the errors array.

const isCode = src.text.startsWith('`') && src.text.endsWith('`');
if (src.text && src.text === trg.text && !isCode) {
  errors.push(`Untranslated Text: Asset #${i+1} still says "${src.text}"`);
}

If the target URL is a relative path, it should not contain non-English characters. This is valid for ASCII, but some valid URLs might contain encoded UTF-8 characters. Please ensure the paths in the blog posts remain ASCII.

// For relative paths, we ensure they aren't accidentally translated into words
// (e.g., ../assets/ changed to ../activos/)
if (trg.url.match(/[^\x00-\x7F]/)) { 
    errors.push(`Relative Path Error: Path "${trg.url}" contains non-English characters.`);
}

The script prints the error messages if the errors array is not empty. Upon successful validation, the script displays a success message.

if (errors.length > 0) {
console.log('❌ Integrity & Translation Errors:');
errors.forEach(err => console.log(`  - ${err}`));
} else {
console.log('✅ Asset integrity and translation checks passed.');
}

When the externalLinksToCheck array is not empty, the target blog post contains external URLs that require connectivity checking. The validateConnectivity makes at least one fetch call on the target URL and waits for the response result. When the response is not ok, the script detects broken links and logs the error to the console.

async function validateConnectivity(urls) {
  const results = await Promise.all(urls.map(async (url) => {
    try {
      let response = await fetch(url, { method: 'HEAD', signal: AbortSignal.timeout(5000) });
      if (!response.ok) response = await fetch(url, { method: 'GET', signal: AbortSignal.timeout(5000) });
      return { url, ok: response.ok, status: response.status };
    } catch (e) {
      return { url, ok: false, status: 'Error/Timeout' };
    }
  }));

  results.forEach(res => {
    if (!res.ok) console.log(`  ❌ [${res.status}] ${res.url}`);
  });
}

if (src.url.startsWith('http')) {
  if (src.url !== trg.url) {
    errors.push(`URL Mismatch: Source "${src.url}" vs Target "${trg.url}"`);
  }
  externalLinksToCheck.push(trg.url);
}

if (externalLinksToCheck.length > 0) {
  console.log(`\nChecking connectivity for ${externalLinksToCheck.length} external links...`);
  await validateConnectivity(externalLinksToCheck);
}

We can find the script in the scripts folder.

Next, make the script executable using the Linux chmod command in a macOS/Linux environment.

chmod a+x check-links.js

The Specification

The skill specification is defined in the SKILL.md file. The markdown file starts with the metadata. The metadata has the skill name and description.

Gemini CLI loads the skill name and description at first. When the description matches the keywords in a user prompt, the CLI activates the skill and loads the entire file in the context.

---
name: technical-localization-expert
description: A high-precision localization engine that scans categorized terminology folders in `references/` to ensure domain-specific accuracy. Optimized for English-to-Global technical content with strict code-asset protection.
---

The next few sections are the persona and the logic to perform blog translation.
Category 1 asks Gemini to validate the source is English.

Category 2 asks the model to scan the user prompt to identify the target language (Traditional Chinese) and derives the language code (zhtw). The skill finds references/terminology-en-zhtw folder and loads all the markdown files in it.

# Technical Localization Expert

## PERSONA

You are a Senior Technical Translator and Localization Specialist. You specialize in converting developer-focused English content into various target languages. You prioritize technical accuracy, character set integrity, and the absolute preservation of all technical assets.

## LINGUISTIC & MECHANICAL LOGIC

1. **Category 1: Source Language Validation**
    - **Rule:** This skill is strictly optimized for translating **English source text**.
    - **Action:** Analyze the source content before proceeding.
    - **Stop Condition:** If the source language is NOT English, stop processing and notify the user: "⚠️ Notification: This localization engine requires English source text to ensure terminology-to-glossary consistency."

2. **Category 2: Modular Glossary Scanning & Fallback**
    - **Step 1:** Identify the Target Language Code (e.g., Traditional Chinese -> `zhtw`, Spanish -> `es`, Brazilian Portuguese -> `ptbr`).
    - **Step 2:** Locate the folder: `references/terminology-en-[code]/`.
    - **Step 3 (Success):** If the folder exists, read all Markdown files within it (e.g., `cloud.md`, `frontend.md`, `general.md`) to build a comprehensive terminology map.
    - **Step 4 (Fallback):** If the folder does NOT exist, notify the user: "Notice: No custom glossary folder found for [code]. Proceeding with standard regional technical terminology." Revert to internal high-precision standards for that locale.

Categories 3, 4, 5, and 6 are instructions ensuring that the model understands what to do and what not to do. For example, the Alt-text and link texts must be translated to the target language whereas relative paths should be untranslated. Moreover, any text, code, and variables in the single-backtick and triple-backtick blocks should not be translated.

3. **Category 3: Immutable Code Assets (Zero-Touch Policy)**
    - **Hard Rule:** Any text wrapped in single backticks or triple backticks is a **Literal String Block**.
    - **Preservation Instructions:**
        1. **DO NOT** translate any text inside, including code logic, variable names, or comments.
        2. **DO NOT** modify the casing, indentation, or spacing.
        3. **DO NOT** interpret escape characters. If the source contains a backslash followed by a letter (such as n, t, or r), you **MUST** output those literal characters. Do not convert them into actual newlines or tabs.
        4. **Even if the block contains English instructions or prose, it must be treated as raw, immutable data.**
    - **Verification:** Before outputting, check that every character within the backticks matches the source 1:1.

4. **Category 4: Image & Link Asset Protection & Path Adjustment**
    - **External Links:** For `(https://...)`, translate the `Link Text` but leave the `(URL)` verbatim.
    - **Absolute Internal Paths:** For paths starting with `/` (e.g., `/assets/images/logo.png`), leave the path verbatim as it is root-relative.
    - **Relative Paths (Strategy 3 - Path Re-calculation):**
        1. If the target localization file is stored at a different directory depth than the English source (e.g., moving from `blog/post.md` to `zh/blog/post.md`), you **must** recalculate the relative path.
        2. Adjust the number of "upward" steps (e.g., changing `../assets/` to `../../assets/`) to ensure the link remains functional from the new file location.
    - **Alt-Text:** Always translate the `Alt Text` for images and `Link Text` for hyperlinks to the target language, while applying the rules above to the `(URL)` portion.

5. **Category 5: Regional Standards & zh-TW Integrity**
    - **Traditional Chinese (zh-TW):** Strictly use Traditional Chinese characters. Use Taiwan-specific industry standards (e.g., Software -> 軟體, Instance -> 執行個體, Project -> 專案). Ensure zero "bleed" from Simplified Chinese vocabulary.
    - **General:** For any target language, use the professional IT vocabulary of that specific region. Avoid literal "machine" translations.

6. **Category 6: Formatting & Raw String Integrity**
    - **Markdown:** Maintain all Markdown formatting integrity (#, **, *, -, >).
    - **Escape Characters:** Treat code as **raw text**. Do not render `\n` as a physical newline within code blocks or backticks; output the literal characters.
    - **Tone:** Professional, technical "developer-to-developer" tone.
    - **Address:** Use the polite/formal form of address in the target language (e.g., "您" for Chinese, "Usted" for Spanish).

Category 7 specifies the order of execution so that the English blog is translated systematically and with high accuracy.

Category 8 validates the assets to ensure external links are not broken. Only the Alt-text and link texts are translated, and relative paths are excluded.

7. **Category 7: Order of Execution**
    1. **Validate:** Confirm the source is English. (Stop if not).
    2. **Map:** Identify the target ISO code.
    3. **Scan:** Look for the folder `references/terminology-en-[code]/`.
       - **If folder exists:** Ingest all modular glossary files.
       - **If folder missing:** Trigger Fallback Notification and use internal standards.
    4. **Translate:** Execute the translation while strictly protecting all backticks, URLs, and image paths.
    5. **Verify:** **Execute `./scripts/check-links.js`** on the result to identify broken or mismatched URLs.
    6. **Remediate:** If links are broken, fix them based on the English source and re-verify.
    7. **Deliver:** Provide the finalized, verified translation.

8. **Category 8: Quality Assurance & Link Integrity (Mandatory)**
    - **Verification Tool:** `./scripts/check-links.js`.
    - **Logic for Broken Links:**
        1. If the script reports a link as broken, compare it to the original English source.
        2. **Branch A (Translation Error):** If the URL in your translation differs from the source, fix it to match the source exactly and re-run the script.
        3. **Branch B (Source Error):** If the URL matches the source exactly but the script still reports it as broken, categorize it as a **"Pre-existing Source Error."**
        4. **Maximum Retries:** Do not attempt more than 2 correction cycles per link.
    - **Action Audit Report:** At the end of the output, provide a concise summary of the localization actions taken, including:
        - **Source Validation:** Confirmation that the source was English.
        - **Glossary Status:** Identification of the glossary folder used (e.g., `references/terminology-en-[code]/`) or if the "Fallback" was triggered.
        - **Asset Protection:** Confirmation that all text within single and triple backticks was preserved 1:1 as per Category 3.
        - **Link Integrity:** Results of the link verification (e.g., "All links verified" or "Pre-existing Source Errors identified").
    - **Final Action:** If errors persist after retries, deliver the translation and list all persistent errors within the Link Integrity section of the Audit Report.

Installing the Skill

With the specification defined, static terminology files, and validation script for the translate blog post skill in the technical-localization-expert directory. We can copy the directory to ~/.gemini/skills to make it available to the Gemini CLI.

The technical-localization-expert folder contains the following files: SKILL.md, references, and scripts folders.

technical-localization-expert
├── references
│   └── terminology-en-zhtw
│       ├── ai.md
│       ├── backend.md
│       ├── cloud.md
│       ├── frontend.md
│       ├── general.md
│       ├── internet.md
│       └── web.md
├── scripts
│   └── check-links.js
└── SKILL.md

Copy the entire technical-localization-expert folder to ~/.gemini/skills. Then, list the content of ~/.gemini/skills/technical-localization-expert to verify.

mkdir -p ~/.gemini/skills/technical-localization-expert

cd ~/technical-localization-expert 
cp -r ./technical-localization-expert/* ~/.gemini/skills/technical-localization-expert
ls ~/.gemini/skills/technical-localization-expert

After copying the directory successfully, I restart the Gemini CLI to translate a blog post to Traditional Chinese.

The Workflow in Action

Change the directory to the folder where my blog post is located. Then, launch the Gemini CLI on the terminal

cd markdown
gemini

Enter the following command in the Gemini CLI:

use the technical-localization-expert skill to translate @mastering_live_sports_data_with_gemini_3.md to Traditional Chinese and write the translation to chinese-blogs/translated3.md        

This user prompt instructs the CLI to use the skill to translate a blog post in the current directory to Traditional Chinese. The Traditional Chinese blog post is saved to chinese-blogs/translated3.md.

The CLI discovers the technical-localization-expert skill and prompts me to activate it.

Then, the CLI loads the terminology files from the references/terminology-en-zhtw folder and the skill executes the cat linux command to injest the English blog post into the model's context window dynamically.

Next, the skill extracts the technical terms from the files, injects them and the English blog text into the prompt to generate a Traditional Chinese blog. It activates the link validation script to extract and validate the links in the translated text.

The links in the translated text are valid and match the ones in the English blog post. The content is saved to chinese-blogs/translated3.md for further review and publication.

Finally, the skill prints the audit report to list all the completed steps of that localization process. The skill detects English content, applies Taiwan technology terminology during the translation, preserves any text in the triple backticks, and verifies the links in the translated text match the original and reachable.

Conclusion

By orchestrating the terminology files and the link validation script in an agent skill, I can now translate English posts into Traditional Chinese with a single skill in Gemini CLI. This ensures every technical term is accurate and every link works. This workflow allows me to publish confidently to Taiwan Facebook Groups and global platforms in the future.

How would you use Gemini CLI and Agent Skill to increase your impact in the communities globally?

Resources

• Google AI Studio (For API Keys)
• Gemini CLI Get Started with Agent Skill
• Gemini CLI Agent Skills