Using comment with i18n-check: to match dynamic translation keys

lunny · lunny · commit c668142c8472 · 2025-07-01T12:57:35.000-07:00
diff --git a/models/actions/runner.go b/models/actions/runner.go
@@ -114,6 +114,7 @@ func (r *ActionRunner) StatusName() string {
 }
 
 func (r *ActionRunner) StatusLocaleName(lang translation.Locale) string {
+	// i18n-check: actions.runners.status.*
 	return lang.TrString("actions.runners.status." + r.StatusName())
 }
 
diff --git a/models/actions/status.go b/models/actions/status.go
@@ -43,6 +43,7 @@ func (s Status) String() string {
 
 // LocaleString returns the locale string name of the Status
 func (s Status) LocaleString(lang translation.Locale) string {
+	// i18n-check: actions.status.*
 	return lang.TrString("actions.status." + s.String())
 }
 
diff --git a/models/git/commit_status.go b/models/git/commit_status.go
@@ -206,6 +206,7 @@ func (status *CommitStatus) APIURL(ctx context.Context) string {
 
 // LocaleString returns the locale string name of the Status
 func (status *CommitStatus) LocaleString(lang translation.Locale) string {
+	// i18n-check: repo.commitstatus.*
 	return lang.TrString("repo.commitstatus." + status.State.String())
 }
 
diff --git a/models/issues/comment.go b/models/issues/comment.go
@@ -225,11 +225,13 @@ const (
 
 // LocaleString returns the locale string name of the role
 func (r RoleInRepo) LocaleString(lang translation.Locale) string {
+	// i18n-check: repo.issues.role.*
 	return lang.TrString("repo.issues.role." + string(r))
 }
 
 // LocaleHelper returns the locale tooltip of the role
 func (r RoleInRepo) LocaleHelper(lang translation.Locale) string {
+	// i18n-check: repo.issues.role.*_helper
 	return lang.TrString("repo.issues.role." + string(r) + "_helper")
 }
 
diff --git a/modules/auth/password/password.go b/modules/auth/password/password.go
@@ -128,6 +128,7 @@ func BuildComplexityError(locale translation.Locale) template.HTML {
 	buffer.WriteString("<ul>")
 	for _, c := range requiredList {
 		buffer.WriteString("<li>")
+		// i18n-check: form.password_*
 		buffer.WriteString(locale.TrString(c.TrNameOne))
 		buffer.WriteString("</li>")
 	}
diff --git a/modules/translation/i18n/localestore.go b/modules/translation/i18n/localestore.go
@@ -144,6 +144,7 @@ func (l *locale) TrHTML(trKey string, trArgs ...any) template.HTML {
 			args[i] = template.HTMLEscapeString(fmt.Sprint(v))
 		}
 	}
+	// i18n-check: ignore
 	return template.HTML(l.TrString(trKey, args...))
 }
 
diff --git a/modules/translation/translation.go b/modules/translation/translation.go
@@ -238,6 +238,7 @@ func (l *locale) TrN(cnt any, key1, keyN string, args ...any) template.HTML {
 	} else if t, ok := cnt.(int64); ok {
 		c = t
 	} else {
+		// i18n-check: ignore
 		return l.Tr(keyN, args...)
 	}
 
diff --git a/modules/web/middleware/binding.go b/modules/web/middleware/binding.go
@@ -104,8 +104,10 @@ func Validate(errs binding.Errors, data map[string]any, f Form, l translation.Lo
 
 			trName := field.Tag.Get("locale")
 			if len(trName) == 0 {
+				// i18n-check: form.*
 				trName = l.TrString("form." + field.Name)
 			} else {
+				// i18n-check: ignore
 				trName = l.TrString(trName)
 			}
 
diff --git a/routers/web/admin/admin.go b/routers/web/admin/admin.go
@@ -180,6 +180,7 @@ func DashboardPost(ctx *context.Context) {
 			task := cron.GetTask(form.Op)
 			if task != nil {
 				go task.RunWithUser(ctx.Doer, nil)
+				// i18n-check: admin.dashboard.*
 				ctx.Flash.Success(ctx.Tr("admin.dashboard.task.started", ctx.Tr("admin.dashboard."+form.Op)))
 			} else {
 				ctx.Flash.Error(ctx.Tr("admin.dashboard.task.unknown", form.Op))
diff --git a/routers/web/repo/actions/view.go b/routers/web/repo/actions/view.go
@@ -847,6 +847,7 @@ func Run(ctx *context_module.Context) {
 	})
 	if err != nil {
 		if errLocale := util.ErrorAsLocale(err); errLocale != nil {
+			// i18n-check: ignore
 			ctx.Flash.Error(ctx.Tr(errLocale.TrKey, errLocale.TrArgs...))
 			ctx.Redirect(redirectURL)
 		} else {
diff --git a/routers/web/repo/activity.go b/routers/web/repo/activity.go
@@ -51,6 +51,7 @@ func Activity(ctx *context.Context) {
 	}
 	ctx.Data["DateFrom"] = timeFrom
 	ctx.Data["DateUntil"] = timeUntil
+	// i18n-check: repo.activity.period.*
 	ctx.Data["PeriodText"] = ctx.Tr("repo.activity.period." + ctx.Data["Period"].(string))
 
 	canReadCode := ctx.Repo.CanRead(unit.TypeCode)
diff --git a/routers/web/repo/editor_error.go b/routers/web/repo/editor_error.go
@@ -39,6 +39,7 @@ func editorHandleFileOperationErrorRender(ctx *context_service.Context, message,
 
 func editorHandleFileOperationError(ctx *context_service.Context, targetBranchName string, err error) {
 	if errAs := util.ErrorAsLocale(err); errAs != nil {
+		// i18n-check: ignore
 		ctx.JSONError(ctx.Tr(errAs.TrKey, errAs.TrArgs...))
 	} else if errAs, ok := errorAs[git.ErrNotExist](err); ok {
 		ctx.JSONError(ctx.Tr("repo.editor.file_modifying_no_longer_exists", errAs.RelPath))
diff --git a/routers/web/repo/migrate.go b/routers/web/repo/migrate.go
@@ -318,6 +318,7 @@ func MigrateStatus(ctx *context.Context) {
 				Args:   []any{task.Message},
 			}
 		}
+		// i18n-check: repo.migrate.migrating_failed.*
 		message = ctx.Locale.TrString(translatableMessage.Format, translatableMessage.Args...)
 	}
 
diff --git a/services/context/base.go b/services/context/base.go
@@ -167,6 +167,7 @@ func (b *Base) ServeContent(r io.ReadSeeker, opts *ServeHeaderOptions) {
 }
 
 func (b *Base) Tr(msg string, args ...any) template.HTML {
+	// i18n-check: ignore
 	return b.Locale.Tr(msg, args...)
 }
 
diff --git a/services/cron/setting.go b/services/cron/setting.go
@@ -70,6 +70,7 @@ func (b *BaseConfig) DoNoticeOnSuccess() bool {
 // Please note the `status` string will be concatenated with `admin.dashboard.cron.` and `admin.dashboard.task.` to provide locale messages. Similarly `name` will be composed with `admin.dashboard.` to provide the locale name for the task.
 func (b *BaseConfig) FormatMessage(locale translation.Locale, name, status, doer string, args ...any) string {
 	realArgs := make([]any, 0, len(args)+2)
+	// i18n-check: admin.dashboard.*
 	realArgs = append(realArgs, locale.TrString("admin.dashboard."+name))
 	if doer == "" {
 		realArgs = append(realArgs, "(Cron)")
@@ -80,7 +81,9 @@ func (b *BaseConfig) FormatMessage(locale translation.Locale, name, status, doer
 		realArgs = append(realArgs, args...)
 	}
 	if doer == "" {
+		// i18n-check: admin.dashboard.cron.*
 		return locale.TrString("admin.dashboard.cron."+status, realArgs...)
 	}
+	// i18n-check: admin.dashboard.task.*
 	return locale.TrString("admin.dashboard.task."+status, realArgs...)
 }
diff --git a/services/cron/tasks.go b/services/cron/tasks.go
@@ -159,6 +159,7 @@ func RegisterTask(name string, config Config, fun func(context.Context, *user_mo
 	log.Debug("Registering task: %s", name)
 
 	i18nKey := "admin.dashboard." + name
+	// i18n-check: admin.dashboard.*
 	if value := translation.NewLocale("en-US").TrString(i18nKey); value == i18nKey {
 		return fmt.Errorf("translation is missing for task %q, please add translation for %q", name, i18nKey)
 	}
diff --git a/tools/i18n/check.go b/tools/i18n/check.go
@@ -6,6 +6,7 @@
 package main
 
 import (
+	"fmt"
 	"go/ast"
 	"go/parser"
 	"go/token"
@@ -87,14 +88,63 @@ func searchUnusedKeyInFile(dir, path string, keys []string, res *[]bool) error {
 	return nil
 }
 
+func searchUntranslatedKeyInCall(path string, fset *token.FileSet, astf *ast.File, call *ast.CallExpr, arg ast.Expr, keys []string) string {
+	if lit, ok := arg.(*ast.BasicLit); ok && lit.Kind == token.STRING {
+		key := strings.Trim(lit.Value, `"`)
+		if !slices.Contains(keys, key) {
+			return key
+		}
+		return ""
+	}
+
+	var lastCg *ast.CommentGroup
+	for _, cg := range astf.Comments {
+		if cg.End() < call.Pos() {
+			if lastCg == nil || cg.End() > lastCg.End() {
+				lastCg = cg
+			}
+		}
+	}
+	if lastCg == nil {
+		fmt.Printf("no comment found for a dynamic translation key: %s:%d\n", path, fset.Position(call.Pos()).Line)
+		os.Exit(1)
+		return ""
+	}
+
+	transKeyMatch, ok := strings.CutPrefix(lastCg.Text(), "i18n-check:")
+	if !ok {
+		fmt.Printf("no comment found for a dynamic translation key: %s:%d\n", path, fset.Position(call.Pos()).Line)
+		os.Exit(1)
+		return ""
+	}
+	transKeyMatch = strings.TrimSpace(transKeyMatch)
+	switch transKeyMatch {
+	case "ignore": // i18n-check: ignore
+		return ""
+	default: // i18n-check: <transKeyMatch>
+		g := glob.MustCompile(transKeyMatch)
+		found := false
+		for _, key := range keys {
+			if g.Match(key) {
+				found = true
+				break
+			}
+		}
+		if !found {
+			return transKeyMatch
+		}
+	}
+	return ""
+}
+
 func searchUntranslatedKeyInGoFile(dir, path string, keys []string) ([]string, error) {
 	if filepath.Ext(path) != ".go" || strings.HasSuffix(path, "_test.go") {
 		return nil, nil
 	}
 
 	var untranslated []string
 	fs := token.NewFileSet()
-	node, err := parser.ParseFile(fs, path, nil, 0)
+	node, err := parser.ParseFile(fs, path, nil, parser.ParseComments)
 	if err != nil {
 		return nil, err
 	}
@@ -108,26 +158,17 @@ func searchUntranslatedKeyInGoFile(dir, path string, keys []string) ([]string, e
 			switch funIdent.Sel.Name {
 			case "Tr", "TrString":
 				if len(call.Args) >= 1 {
-					if lit, ok := call.Args[0].(*ast.BasicLit); ok && lit.Kind == token.STRING {
-						key := strings.Trim(lit.Value, `"`)
-						if !slices.Contains(keys, key) {
-							untranslated = append(untranslated, key)
-						}
+					if key := searchUntranslatedKeyInCall(path, fs, node, call, call.Args[0], keys); key != "" {
+						untranslated = append(untranslated, key)
 					}
 				}
 			case "TrN":
 				if len(call.Args) >= 3 {
-					if lit, ok := call.Args[1].(*ast.BasicLit); ok && lit.Kind == token.STRING {
-						key := strings.Trim(lit.Value, `"`)
-						if !slices.Contains(keys, key) {
-							untranslated = append(untranslated, key)
-						}
+					if key := searchUntranslatedKeyInCall(path, fs, node, call, call.Args[1], keys); key != "" {
+						untranslated = append(untranslated, key)
 					}
-					if lit, ok := call.Args[2].(*ast.BasicLit); ok && lit.Kind == token.STRING {
-						key := strings.Trim(lit.Value, `"`)
-						if !slices.Contains(keys, key) {
-							untranslated = append(untranslated, key)
-						}
+					if key := searchUntranslatedKeyInCall(path, fs, node, call, call.Args[2], keys); key != "" {
+						untranslated = append(untranslated, key)
 					}
 				}
 			}
@@ -205,29 +246,6 @@ func searchUnTranslatedKeyInFile(dir, path string, keys []string) ([]string, err
 	return append(untranslatedKeys, untranslatedKeysInTmpl...), nil
 }
 
-var whitelist = []string{
-	"repo.signing.wont_sign.*",
-	"repo.issues.role.*",
-	"repo.commitstatus.*",
-	"admin.dashboard.*",
-	"admin.dashboard.cron.*",
-	"admin.dashboard.task.*",
-	"repo.migrate.*.description",
-	"actions.runners.status.*",
-	"projects.*.display_name",
-	"admin.notices.*",
-	"form.NewBranchName", // FIXME: used in integration tests only
-}
-
-func isWhitelisted(key string) bool {
-	for _, w := range whitelist {
-		if glob.MustCompile(w).Match(key) {
-			return true
-		}
-	}
-	return false
-}
-
 func main() {
 	if len(os.Args) != 1 {
 		println("usage: clean-locales")
@@ -248,9 +266,6 @@ func main() {
 			} else {
 				trKey = section.Name() + "." + key.Name()
 			}
-			if isWhitelisted(trKey) {
-				continue
-			}
 			keys = append(keys, trKey)
 		}
 	}

Original file line number	Diff line number	Diff line change
`@@ -114,6 +114,7 @@ func (r *ActionRunner) StatusName() string {`
`114`	`114`	`}`
`115`	`115`
`116`	`116`	`func (r *ActionRunner) StatusLocaleName(lang translation.Locale) string {`
	`117`	`+ // i18n-check: actions.runners.status.*`
`117`	`118`	`return lang.TrString("actions.runners.status." + r.StatusName())`
`118`	`119`	`}`
`119`	`120`
Original file line number	Diff line number	Diff line change
`@@ -43,6 +43,7 @@ func (s Status) String() string {`
`43`	`43`
`44`	`44`	`// LocaleString returns the locale string name of the Status`
`45`	`45`	`func (s Status) LocaleString(lang translation.Locale) string {`
	`46`	`+ // i18n-check: actions.status.*`
`46`	`47`	`return lang.TrString("actions.status." + s.String())`
`47`	`48`	`}`
`48`	`49`
Original file line number	Diff line number	Diff line change
`@@ -206,6 +206,7 @@ func (status *CommitStatus) APIURL(ctx context.Context) string {`
`206`	`206`
`207`	`207`	`// LocaleString returns the locale string name of the Status`
`208`	`208`	`func (status *CommitStatus) LocaleString(lang translation.Locale) string {`
	`209`	`+ // i18n-check: repo.commitstatus.*`
`209`	`210`	`return lang.TrString("repo.commitstatus." + status.State.String())`
`210`	`211`	`}`
`211`	`212`
Original file line number	Diff line number	Diff line change
`@@ -225,11 +225,13 @@ const (`
`225`	`225`
`226`	`226`	`// LocaleString returns the locale string name of the role`
`227`	`227`	`func (r RoleInRepo) LocaleString(lang translation.Locale) string {`
	`228`	`+ // i18n-check: repo.issues.role.*`
`228`	`229`	`return lang.TrString("repo.issues.role." + string(r))`
`229`	`230`	`}`
`230`	`231`
`231`	`232`	`// LocaleHelper returns the locale tooltip of the role`
`232`	`233`	`func (r RoleInRepo) LocaleHelper(lang translation.Locale) string {`
	`234`	`+ // i18n-check: repo.issues.role.*_helper`
`233`	`235`	`return lang.TrString("repo.issues.role." + string(r) + "_helper")`
`234`	`236`	`}`
`235`	`237`
Original file line number	Diff line number	Diff line change
`@@ -128,6 +128,7 @@ func BuildComplexityError(locale translation.Locale) template.HTML {`
`128`	`128`	`buffer.WriteString("<ul>")`
`129`	`129`	`for _, c := range requiredList {`
`130`	`130`	`buffer.WriteString("<li>")`
	`131`	`+ // i18n-check: form.password_*`
`131`	`132`	`buffer.WriteString(locale.TrString(c.TrNameOne))`
`132`	`133`	`buffer.WriteString("</li>")`
`133`	`134`	`}`
Original file line number	Diff line number	Diff line change
`@@ -144,6 +144,7 @@ func (l *locale) TrHTML(trKey string, trArgs ...any) template.HTML {`
`144`	`144`	`args[i] = template.HTMLEscapeString(fmt.Sprint(v))`
`145`	`145`	`}`
`146`	`146`	`}`
	`147`	`+ // i18n-check: ignore`
`147`	`148`	`return template.HTML(l.TrString(trKey, args...))`
`148`	`149`	`}`
`149`	`150`
Original file line number	Diff line number	Diff line change
`@@ -238,6 +238,7 @@ func (l *locale) TrN(cnt any, key1, keyN string, args ...any) template.HTML {`
`238`	`238`	`} else if t, ok := cnt.(int64); ok {`
`239`	`239`	`c = t`
`240`	`240`	`} else {`
	`241`	`+ // i18n-check: ignore`
`241`	`242`	`return l.Tr(keyN, args...)`
`242`	`243`	`}`
`243`	`244`
Original file line number	Diff line number	Diff line change
`@@ -104,8 +104,10 @@ func Validate(errs binding.Errors, data map[string]any, f Form, l translation.Lo`
`104`	`104`
`105`	`105`	`trName := field.Tag.Get("locale")`
`106`	`106`	`if len(trName) == 0 {`
	`107`	`+ // i18n-check: form.*`
`107`	`108`	`trName = l.TrString("form." + field.Name)`
`108`	`109`	`} else {`
	`110`	`+ // i18n-check: ignore`
`109`	`111`	`trName = l.TrString(trName)`
`110`	`112`	`}`
`111`	`113`