Comfy-Org / Comfy-Org/ComfyUI_frontend

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

Open
#3,493 0 comments 0 reactions 0 assignees View on GitHub
area:i18n help wanted
Dominant language
TypeScript
Stars
2k
Forks
699
Avg merge
1d 7h
Merged PRs (30d)
490

Description

## 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](https://github.com/Comfy-Org/workflow_templates#adding-a-new-template) 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`
```typescript
// 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**
```bash
# 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**
```typescript
// 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:**
```typescript
// 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):**
```typescript
// 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):**
```typescript
// 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](https://github.com/Comfy-Org/workflow_templates)
- [Template Submission Process](https://github.com/Comfy-Org/workflow_templates#adding-a-new-template)
- [lobe-i18n Documentation](https://github.com/lobehub/lobe-cli-toolbox/blob/master/packages/lobe-i18n/README.md)
- [Frontend i18n Documentation](/src/locales/README.md)

**Related Issues/PRs:**
- Commit `c24472ae`: Template localization implementation
- PR #3769: Template workflow descriptions localization

┆Issue is synchronized with this [Notion page](https://www.notion.so/Issue-3493-DevTask-Decouple-template-translations-Create-independent-CI-for-workflow-templates-1d86d73d3650814a9416c308e499abdf) by [Unito](https://www.unito.io)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.