How Language-Specific Mode Directories Work in career-ops

Career-ops supports multilingual AI assistance through language-specific subdirectories under modes/, activated either via session commands or persistent profile configuration.

The open-source career-ops repository by santifer provides localized AI assistant behaviors for job seekers through a modular directory structure. While default English mode files reside in the root modes/ directory, the repository implements language-specific mode directories such as modes/de/ and modes/fr/ to support German and French markets. This architecture allows users to interact with the AI assistant in their native language while maintaining technical consistency across the codebase.

Directory Structure and File Organization

The Root modes/ Directory

The default English (and Spanish) mode files live in modes/ at the repository root. These files—including offer.md, apply.md, and pipeline.md—define the AI assistant's behavior for job evaluation, application assistance, and pipeline management. When no language override is specified, the system sources mode files from this location.

Language-Specific Subdirectories

For non-English markets, career-ops provides dedicated subdirectories following the pattern modes/<language_code>/. Currently implemented examples include:

• modes/de/ – German localization
• modes/fr/ – French localization

Each directory contains translated versions of high-impact modes. For example, modes/de/angebot.md provides the German equivalent of offer.md, while modes/fr/postuler.md handles French application assistance. The CLI can target these files directly using path arguments (e.g., node career-ops.mjs --mode modes/de/angebot.md).

Shared Context Files

Every language directory includes a localized _shared.md file containing common archetypes, global rules, and market-specific details. The hierarchy follows this pattern:

• modes/_shared.md – English base context
• modes/de/_shared.md – German translated context
• modes/fr/_shared.md – French translated context

These shared files ensure consistent terminology and cultural context across all modes within a specific language pack.

Translated Modes vs. Language-Agnostic Tools

High-Impact Translated Modes

Only the four primary workflow modes receive full translation treatment in each language pack:

1. Offer evaluation – oferta.md (EN/ES) translates to angebot.md (DE) and offre.md (FR)
2. Apply assistant – apply.md (EN) translates to bewerben.md (DE) and postuler.md (FR)
3. Pipeline – pipeline.md remains the filename but contains localized content
4. Shared context – _shared.md with market-specific localization

This selective approach ensures core job-search workflows feel native to the user while minimizing maintenance overhead.

Technical Tooling Modes

Language-agnostic modes remain in the root modes/ directory and are not duplicated. These include scan, pdf, tracker, and other utility modes that primarily contain commands, file paths, or code snippets. Since these modes interact with technical infrastructure rather than natural language processing, they function identically across all language configurations.

Activation Methods

Per-Session Command Activation

Users can activate language-specific modes for a single conversation by instructing the AI assistant at the start of the chat. For example:

Nutze ab jetzt die deutschen Modi unter modes/de/.

Or for French:

Utilise les modes francais sous modes/fr/.

When activated this way, the assistant reads mode files from the specified subdirectory instead of the default modes/ root for the duration of that session.

Persistent Profile Configuration

For permanent language preference, users configure the config/profile.yml file with a language block:

language:
  primary: de
  modes_dir: modes/de

After setting language.modes_dir to point to the desired language directory (e.g., modes/de or modes/fr), users should remind the AI in the first session to respect this field. Subsequent interactions will automatically load modes from the specified directory. Note that this language.modes_dir key represents a repository convention rather than hard-coded schema, allowing maintainers flexibility in configuration naming.

Implementation Details and Conventions

Preserving English Technical Identifiers

Across all language packs, technical identifiers remain in English to ensure CLI and script compatibility. This includes file references like cv.md, status values such as Evaluated and Applied, and tool names like Playwright or WebFetch. The translation layer focuses on user-facing instructions and natural language processing while keeping code-facing strings stable.

Vocabulary Consistency

Each language directory includes a README (e.g., modes/de/README.md or modes/fr/README.md) containing a vocabulary cheat-sheet mapping English terms to preferred local equivalents. For instance, German users will see "Job posting" mapped to "Stellenanzeige," while French users see "Job posting" mapped to "Offre d'emploi." When extending or customizing modes, maintainers should follow these lexicons to ensure tonal consistency with the existing language pack.

Summary

• Language-specific mode directories live under modes/<language_code>/ (e.g., modes/de/, modes/fr/) and contain translated versions of core workflow files.
• Four primary modes receive translation treatment: offer evaluation, apply assistant, pipeline, and shared context, while technical tooling modes remain in the root modes/ directory.
• Activation occurs either through per-session natural language commands or by setting language.modes_dir in config/profile.yml for persistent configuration.
• Technical identifiers (status values, tool names, file references) remain English across all language packs to maintain script compatibility.
• Shared context files (_shared.md) provide localized archetypes and market rules for each supported language.

Frequently Asked Questions

What files are included in language-specific mode directories?

Each language directory contains translated versions of the four primary workflow modes: offer evaluation (angebot.md/offre.md), application assistance (bewerben.md/postuler.md), pipeline management (pipeline.md), and shared context (_shared.md). Technical modes like scan.md, pdf.md, and tracker.md remain in the root modes/ directory and are not duplicated, as they contain primarily code and file paths rather than natural language content.

How do I switch to German or French modes permanently?

Create or edit config/profile.yml to include a language block specifying the primary language code and modes_dir path. For German, set modes_dir: modes/de; for French, use modes_dir: modes/fr. After configuring this file, inform the AI assistant in your first session to respect the language.modes_dir setting, and it will automatically load files from that directory for all future interactions.

Why do some mode files remain in English only?

Technical tooling modes (such as scan, pdf, and tracker) contain commands, CLI instructions, and code references that function identically regardless of user language. Translating these would create maintenance overhead without improving functionality, as the AI processes these as technical instructions rather than conversational content. Only user-facing conversational modes receive full translation.

Where is the language configuration stored?

The primary configuration resides in config/profile.yml under the language key, specifically using language.primary for the language code and language.modes_dir for the directory path. Additionally, each language pack includes its own README (e.g., modes/de/README.md) documenting activation instructions and vocabulary standards for that specific language.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}