[DevTask] Decouple template translations: Create independent CI for workflow templates package translation system

Background/Context

Current Translation Architecture:

• The Comfy-Org/workflow_templates package contains templates with metadata but no translation system
• Template translations are manually added to ComfyUI_frontend/src/locales/*/main.json files
• This creates a tight coupling where template package updates require frontend changes
• The 12-step template submission process specifically mentions needing to "add translations to ComfyUI_frontend" (Step 12)

Why This Matters:

• Scalability: As template contributions grow, the frontend becomes a bottleneck for template localization
• Maintainability: Template authors need to coordinate across two repositories
• Autonomy: Template packages should be self-contained for localization
• API Stability: Reduces coupling between template distribution and frontend updates

Problem Statement

Current Behavior:

1. Template authors add templates to workflow_templates repository
2. Template metadata includes English-only names/descriptions
3. Translations must be manually added to ComfyUI_frontend locales
4. Frontend CI handles all translation automation via lobe-i18n + OpenAI API
5. Template package remains translation-agnostic

Expected Behavior:

1. Template packages should include their own translation infrastructure
2. Template translations should be generated independently of frontend
3. Frontend should consume pre-translated template data via API
4. Template CI should mirror frontend's automated translation system

Impact:

• Template Contributors: Must coordinate across repositories for full localization
• Frontend Maintainers: Handle translation burden for external packages
• International Users: Experience delays in template localization
• System Architecture: Unnecessary coupling between concerns

Root Cause Analysis

Technical Debt Location: src/stores/workflowTemplatesStore.ts:89-120

// Current tight coupling - template store handles frontend translations
const localizedTemplate: LocalizedWorkflowTemplate = {
  ...template,
  display_name: i18n.t(`templateWorkflows.templateDisplayName.${template.name}`) || template.display_name,
  description: i18n.t(`templateWorkflows.templateDescription.${template.category}.${template.name}`) || template.description,
  category_display_name: i18n.t(`templateWorkflows.category.${template.category}`) || template.category
}

Architectural Issue:

• Template package provides English-only metadata
• Frontend store layer performs runtime translation lookup
• Translation keys are hardcoded based on template structure
• No fallback mechanism for missing translations

Historical Context (commit c24472ae):

• Recent addition of template localization tightly integrated with frontend i18n
• 811 lines of translation additions across 7 languages
• Pattern established for frontend-managed template translations

Proposed Solution

Recommended Approach: Independent Translation Infrastructure

1. Create Template Package Translation System

# In workflow_templates repository
├── i18n/
│   ├── en.json (source)
│   ├── zh.json (generated)
│   ├── ja.json (generated)
│   └── ... (other locales)
├── .github/workflows/
│   └── i18n.yaml (mirrors frontend CI)
├── scripts/
│   └── generate-template-translations.ts
└── package.json (add lobe-i18n dependency)

2. Template API Enhancement

• Modify /workflow_templates endpoint to accept locale parameter
• Return pre-translated template metadata
• Maintain backward compatibility with English fallbacks

3. Frontend Store Simplification

// Simplified store - templates come pre-translated
const templates = await api.getWorkflowTemplates(currentLocale)
// No client-side translation needed

Alternative Approach: Shared Translation Service

Create a centralized translation service that both repositories can consume:

• Shared translation keys registry
• Common CI/CD translation pipeline
• API-based translation delivery

Pros/Cons Analysis:

Approach	Pros	Cons
Independent	Full decoupling, package autonomy, mirrors existing frontend pattern	Duplication of translation infrastructure
Shared Service	Single source of truth, reduced duplication	Additional complexity, new dependency

Recommendation: Independent Translation Infrastructure - mirrors the proven frontend pattern and achieves complete decoupling.

Testing Considerations

Verification Steps:

1. Template package generates translations automatically on template updates
2. Frontend can consume localized templates without fallback translation
3. Missing translations gracefully fall back to English
4. Translation keys remain consistent across template updates
5. CI pipeline catches translation regressions

Test Requirements:

// Template package tests
describe('Template Translation CI', () => {
  test('generates translations for all supported locales')
  test('validates translation key consistency')
  test('handles template addition/removal')
})

// Frontend integration tests  
describe('Template Store Integration', () => {
  test('consumes pre-translated templates')
  test('handles missing locale gracefully')
  test('no longer performs client-side translation')
})

Edge Cases:

• New template added without English description
• Template removed but translations persist
• Locale added to frontend but not template package
• API backward compatibility for existing clients

Implementation Checklist

Phase 1: Template Package Translation Infrastructure

• Add @lobehub/i18n-cli dependency to workflow_templates
• Create i18n/ directory structure
• Extract template strings to en.json translation file
• Set up GitHub Actions workflow mirroring frontend i18n.yaml
• Configure OpenAI API integration for automated translation
• Update template schema to include translation metadata

Phase 2: API Enhancement

• Modify /workflow_templates endpoint to accept locale parameter
• Update template response format to include pre-translated fields
• Implement graceful fallback to English for missing translations
• Add API documentation for new locale parameter
• Maintain backward compatibility for existing API consumers

Phase 3: Frontend Decoupling

• Update workflowTemplatesStore.ts to request localized templates
• Remove client-side template translation logic
• Clean up template translation keys from frontend locale files
• Update template components to use pre-translated data
• Add integration tests for new API consumption

Phase 4: Documentation & Migration

• Update template submission process (remove Step 12)
• Create migration guide for existing template translations
• Update API documentation
• Add troubleshooting guide for translation issues

Supporting Materials

Code Examples

Before (Current Coupling):

// Frontend handles all template translation
const localizedTemplate = {
  display_name: i18n.t(`templateWorkflows.templateDisplayName.${template.name}`) || template.display_name,
  description: i18n.t(`templateWorkflows.templateDescription.${template.category}.${template.name}`) || template.description
}

After (Decoupled):

// Templates come pre-translated from API
const templates = await api.getWorkflowTemplates({ locale: 'ja' })
// Templates already contain localized display_name, description

Visual Architecture

CURRENT (Coupled):
[Template Package] → [Frontend] → [Frontend i18n] → [Localized UI]
                     ↑
              Translation Bottleneck

PROPOSED (Decoupled):  
[Template Package] → [Template i18n] → [Localized API] → [Frontend] → [UI]

References and Links

Related Files:

• /src/stores/workflowTemplatesStore.ts:89-120 - Current translation logic
• /src/locales/en/main.json:templateWorkflows - Template translation keys
• /.github/workflows/i18n.yaml - CI pattern to replicate
• /scripts/collect-i18n-general.ts - Translation collection script

External Resources:

• workflow_templates Repository
• Template Submission Process
• lobe-i18n Documentation
• Frontend i18n Documentation

Related Issues/PRs:

• Commit c24472ae: Template localization implementation
• PR #3769: Template workflow descriptions localization

┆Issue is synchronized with this Notion page by Unito