Localization - GitHub Star Tracker

GitHub Star Tracker supports multiple languages for reports and email notifications. All text, including charts, badges, and email content, is localized based on your configuration.

Available Languages

The following languages are currently supported:

English

Code: enLocale: en-USDefault language

Spanish

Code: esLocale: es-ESEspañol

Catalan

Code: caLocale: ca-ESCatalà

Italian

Code: itLocale: it-ITItaliano

Configuration

Set the language using the locale input:

with:
  locale: es

Default Behavior

If you specify an invalid locale, the action will:

Log a warning message
Fall back to English (en)

From src/config/loader.ts:86-89:

const locale = inputLocale || fileConfig.locale || DEFAULTS.locale;
if (!isValidLocale(locale)) {
  core.warning(`Invalid locale "${locale}". Falling back to "en"`);
}

Localized Content

The following content is localized:

Reports

Section headings (Summary, Repositories, Trends, etc.)
Star change descriptions (“stars gained”, “stars lost”, “net change”)
Trend indicators (“up”, “down”, “stable”)
Repository status badges (“NEW”, “REMOVED”)
Chart titles and labels
Forecast section headings and predictions
Stargazer information

Email Notifications

Email subject line
Email body content (HTML formatted)
Sender default name

Badges

Badge text (“Total Stars”)

Charts

Axis labels
Legend text
Chart titles

Language Examples

English (en)

## Summary

- Stars gained: 12
- Stars lost: 3
- Net change: +9

## Repositories

| Repository | Stars | Change | Trend |
|------------|-------|--------|-------|
| my-repo    | 156   | +5     | up    |

Email subject: GitHub Star Tracker Report: 1,234 stars (+12)

Spanish (es)

## Resumen

- Estrellas ganadas: 12
- Estrellas perdidas: 3
- Cambio neto: +9

## Repositorios

| Repositorio | Estrellas | Cambio | Tendencia |
|-------------|-----------|--------|-----------||
| my-repo     | 156       | +5     | subiendo  |

Email subject: Informe de Seguimiento de Estrellas en GitHub: 1,234 estrellas (+12)

Catalan (ca)

## Resum

- Estrelles guanyades: 12
- Estrelles perdudes: 3
- Canvi net: +9

## Repositoris

| Repositori | Estrelles | Canvi | Tendència |
|------------|-----------|-------|-----------||
| my-repo    | 156       | +5    | pujant    |

Email subject: Informe de Seguiment d'Estrelles a GitHub: 1,234 estrelles (+12)

Italian (it)

## Riepilogo

- Stelle guadagnate: 12
- Stelle perse: 3
- Variazione netta: +9

## Repository

| Repository | Stelle | Variazione | Tendenza      |
|------------|--------|------------|---------------|
| my-repo    | 156    | +5         | in aumento    |

Email subject: Report Tracciamento Stelle GitHub: 1,234 stelle (+12)

Translation Keys

The translation system uses JSON files located in src/i18n/. Here are the key categories:

Badge Translations

{
  "badge": {
    "totalStars": "Total Stars"
  }
}

Report Translations

{
  "report": {
    "title": "Star Tracker Report",
    "total": "Total",
    "change": "Change",
    "comparedTo": "Compared to snapshot from {date}",
    "firstRun": "first run",
    "repositories": "Repositories",
    "stars": "Stars",
    "starsCount": "{count} stars",
    "trend": "Trend",
    "newRepositories": "New Repositories",
    "removedRepositories": "Removed Repositories",
    "summary": "Summary",
    "starsGained": "Stars gained",
    "starsLost": "Stars lost",
    "netChange": "Net change"
  }
}

Email Translations

{
  "email": {
    "subject": "GitHub Star Tracker Report",
    "subjectLine": "{subject}: {totalStars} ({delta})",
    "defaultFrom": "GitHub Star Tracker"
  }
}

Trend Translations

{
  "trends": {
    "up": "up",
    "down": "down",
    "stable": "stable"
  }
}

Stargazer Translations

{
  "stargazers": {
    "sectionTitle": "New Stargazers",
    "newStargazers": "{count} new stargazers since last run",
    "starredOn": "starred on {date}",
    "noNewStargazers": "No new stargazers since last run"
  }
}

Forecast Translations

{
  "forecast": {
    "sectionTitle": "Growth Forecast",
    "predictedStars": "Predicted Stars",
    "week": "Week {n}",
    "linearRegression": "Linear Regression",
    "weightedMovingAverage": "Weighted Moving Average",
    "aggregate": "Aggregate Forecast",
    "insufficientData": "Not enough data for forecast (need at least 3 snapshots)"
  }
}

String Interpolation

Translations support variable interpolation using {variable} syntax:

{
  "starsCount": "{count} stars",
  "comparedTo": "Compared to snapshot from {date}",
  "subjectLine": "{subject}: {totalStars} ({delta})"
}

From src/i18n/index.ts:17-21:

export function interpolate({ template, params }: InterpolateParams): string {
  return template.replaceAll(PLACEHOLDER_PATTERN, (match, key) =>
    key in params ? String(params[key]) : match,
  );
}

Workflow Examples

Spanish Reports

.github/workflows/star-tracker-es.yml

name: Seguimiento de Estrellas

on:
  schedule:
    - cron: '0 0 * * 0'

jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Seguir estrellas
        uses: fbuireu/github-star-tracker@v2
        with:
          github-token: ${{ secrets.PAT_TOKEN }}
          locale: es
          
          smtp-host: smtp.gmail.com
          smtp-username: ${{ secrets.SMTP_USERNAME }}
          smtp-password: ${{ secrets.SMTP_PASSWORD }}
          email-to: [email protected]
          email-from: Seguimiento de Estrellas

Catalan Configuration File

star-tracker.yml

# Configuració en català
visibility: public
include_archived: false
include_forks: false
min_stars: 5

locale: ca
include_charts: true
top_repos: 10

Italian with Notifications

.github/workflows/star-tracker-it.yml

name: Tracciamento Stelle

on:
  schedule:
    - cron: '0 0 * * 0'

jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Traccia stelle
        uses: fbuireu/github-star-tracker@v2
        with:
          github-token: ${{ secrets.PAT_TOKEN }}
          locale: it
          
          smtp-host: smtp.gmail.com
          smtp-username: ${{ secrets.SMTP_USERNAME }}
          smtp-password: ${{ secrets.SMTP_PASSWORD }}
          email-to: [email protected]
          email-from: Tracciamento Stelle GitHub

Adding New Languages

To contribute a new language translation:

Create a new JSON file in src/i18n/ (e.g., fr.json for French)
Copy the structure from en.json and translate all strings
Add the locale to LOCALE_MAP in src/config/defaults.ts:

export const LOCALE_MAP = {
  en: 'en-US',
  es: 'es-ES',
  ca: 'ca-ES',
  it: 'it-IT',
  fr: 'fr-FR',  // New language
} as const;

Import and add to TRANSLATIONS in src/i18n/index.ts:

import fr from './fr.json';

const TRANSLATIONS: Record<Locale, Translations> = { en, es, ca, it, fr };

Submit a pull request!

Contributions for additional languages are welcome! See the CONTRIBUTING.md guide.

Implementation Details

The localization system is implemented in src/i18n/index.ts:

export function getTranslations(locale: Locale): Translations {
  return TRANSLATIONS[locale] || FALLBACK_LANG;
}

export function isValidLocale(value: string): value is Locale {
  return LOCALES.includes(value as Locale);
}

Valid locales are: en, es, ca, it

Next Steps

Configuration Overview

Learn about all configuration options

Notifications

Set up email notifications in your language

Get Started

Core Concepts

Configuration

Features

Guides

​Available Languages

English

Spanish

Catalan

Italian

​Configuration

​Default Behavior

​Localized Content

​Reports

​Email Notifications

​Badges

​Charts

​Language Examples

​English (en)

​Spanish (es)

​Catalan (ca)

​Italian (it)

​Translation Keys

​Badge Translations

​Report Translations

​Email Translations

​Trend Translations

​Stargazer Translations

​Forecast Translations

​String Interpolation

​Workflow Examples

​Spanish Reports

​Catalan Configuration File

​Italian with Notifications

​Adding New Languages

​Implementation Details

​Next Steps

Configuration Overview

Notifications

Build docs developers (and LLMs) love

Available Languages

Configuration

Default Behavior

Localized Content

Reports

Email Notifications

Badges

Charts

Language Examples

English (en)

Spanish (es)

Catalan (ca)

Italian (it)

Translation Keys

Badge Translations

Report Translations

Email Translations

Trend Translations

Stargazer Translations

Forecast Translations

String Interpolation

Workflow Examples

Spanish Reports

Catalan Configuration File

Italian with Notifications

Adding New Languages

Implementation Details

Next Steps