Internationalization (i18n) for DEVS

DEVS supports multiple languages. All user-facing strings must be translatable.

Supported Languages

• en - English (default)
• fr - French
• es - Spanish
• de - German
• it - Italian
• ja - Japanese
• zh - Chinese
• ko - Korean
• pt - Portuguese

File Locations

• UI translations: src/i18n/locales/{lang}.ts
• Agent translations: public/agents/*.agent.yaml (i18n section)
• Methodology translations: public/methodologies/*.methodology.yaml (i18n section)

UI Translation Structure

// src/i18n/locales/en.ts
export default {
  common: {
    save: 'Save',
    cancel: 'Cancel',
    delete: 'Delete',
    edit: 'Edit',
    loading: 'Loading...',
    error: 'An error occurred',
  },
  agents: {
    title: 'Agents',
    create: 'Create Agent',
    edit: 'Edit Agent',
    delete: 'Delete Agent',
    name: 'Name',
    role: 'Role',
    instructions: 'Instructions',
  },
  conversations: {
    title: 'Conversations',
    new: 'New Conversation',
    empty: 'No messages yet',
    placeholder: 'Type your message...',
  },
  // ... more sections
}

Using Translations in Components

import { useTranslation } from 'react-i18next'

function MyComponent() {
  const { t } = useTranslation()

  return (
    <div>
      <h1>{t('agents.title')}</h1>
      <Button>{t('common.save')}</Button>

      {/* With interpolation */}
      <p>{t('agents.greeting', { name: agent.name })}</p>

      {/* With pluralization */}
      <p>{t('agents.count', { count: agents.length })}</p>
    </div>
  )
}

Interpolation

// In translation file
{
  greeting: 'Hello, {{name}}!',
  itemCount: '{{count}} item',
  itemCount_plural: '{{count}} items',
}

// In component
t('greeting', { name: 'John' })  // "Hello, John!"
t('itemCount', { count: 1 })     // "1 item"
t('itemCount', { count: 5 })     // "5 items"

Adding a New Translation Key

1. Add the key to src/i18n/locales/en.ts (default language)
2. Add translations to all other language files
3. Use the key in your component with t('section.key')

// 1. Add to en.ts
export default {
  myFeature: {
    title: 'My Feature',
    description: 'This is my new feature',
  },
}

// 2. Add to fr.ts
export default {
  myFeature: {
    title: 'Ma Fonctionnalité',
    description: 'Ceci est ma nouvelle fonctionnalité',
  },
}

// 3. Use in component
const { t } = useTranslation()
<h1>{t('myFeature.title')}</h1>

Agent/Methodology i18n

Add translations directly in YAML files:

id: my-agent
name: My Agent
desc: Short description
role: Role description
instructions: |
  English instructions...

i18n:
  fr:
    name: Mon Agent
    desc: Description courte
    role: Description du rôle
    instructions: |
      Instructions en français...
  es:
    name: Mi Agente
    desc: Descripción corta
    role: Descripción del rol
    instructions: |
      Instrucciones en español...
  de:
    name: Mein Agent
    desc: Kurze Beschreibung
    role: Rollenbeschreibung
    instructions: |
      Anweisungen auf Deutsch...

Critical Rules

1. Use Curly Apostrophe

Always use ' (curly apostrophe) instead of ' (straight apostrophe) in translation strings:

// ✅ Correct
"It's working" // Using '
"Don't forget" // Using '

// ❌ Wrong
"It's working" // Using '
"Don't forget" // Using '

2. Alphabetical Ordering

Keep translation keys in alphabetical order within each section:

export default {
  common: {
    cancel: 'Cancel', // a
    delete: 'Delete', // d
    edit: 'Edit', // e
    save: 'Save', // s
  },
}

3. Consistent Key Naming

Use camelCase for keys, organized by feature:

{
  agents: {
    createNew: 'Create New Agent',
    deleteConfirm: 'Are you sure you want to delete this agent?',
    editTitle: 'Edit Agent',
  },
}

4. No HTML in Translations

Avoid HTML in translation strings. Use Trans component for complex formatting:

import { Trans } from 'react-i18next'

// Instead of: t('message', { link: '<a href="...">' })
;<Trans i18nKey="learnMore">
  Click <a href="/docs">here</a> to learn more.
</Trans>

Adding a New Language

1. Create new locale file: src/i18n/locales/{lang}.ts
2. Copy structure from en.ts and translate all strings
3. Add language code to src/i18n/locales.ts
4. Add language option to settings UI

// src/i18n/locales.ts
export const supportedLocales = [
  { code: 'en', name: 'English' },
  { code: 'fr', name: 'Français' },
  { code: 'es', name: 'Español' },
  { code: 'new', name: 'New Language' }, // Add new language
] as const

Validation

Run type checking to ensure all translation keys are present:

npm run typecheck

Missing translations will cause TypeScript errors if the translation types are properly configured.

Testing Translations

import { describe, it, expect, vi } from 'vitest'

// Mock translations
vi.mock('react-i18next', () => ({
  useTranslation: () => ({
    t: (key: string, params?: object) => {
      if (params) {
        return `${key}:${JSON.stringify(params)}`
      }
      return key
    },
  }),
  Trans: ({ children }: { children: React.ReactNode }) => children,
}))

describe('MyComponent', () => {
  it('renders translated title', () => {
    render(<MyComponent />)
    expect(screen.getByText('myFeature.title')).toBeInTheDocument()
  })
})