gosmopolitan

README

gosmopolitan

简体中文

gosmopolitan checks your Go codebase for code smells that may prove to be hindrance to internationalization ("i18n") and/or localization ("l10n").

The name is a wordplay on "cosmopolitan".

Checks

Currently gosmopolitan checks for the following anti-patterns:

• Occurrences of string literals containing characters from certain writing systems.

  Existence of such strings often means the relevant logic is hard to internationalize, or at least, require special care when doing i18n/l10n.

• Usages of time.Local.

  An internationalized app or library should almost never process time and date values in the timezone in which it is running; instead one should use the respective user preference, or the timezone as dictated by the domain logic.

Caveats

Note that the checks implemented here are only suitable for codebases with the following characteristics, and may not suit your particular project's needs:

• Originally developed for an audience using non-Latin writing system(s),
• Returns bare strings intended for humans containing such non-Latin characters, and
• May occasionally (or frequently) refer to the local timezone.

For example, the lints may prove valuable if you're revamping a web service originally targetting the Chinese market (hence producing strings with Chinese characters all over the place) to be more i18n-aware. Conversely, if you want to identify some of the i18n-naïve places in an English-only app, the linter will output nothing.

golangci-lint integration

gosmopolitan is not integrated into golangci-lint yet, but you can nevertheless run it as a custom plugin.

First make yourself a plugin .so file like this:

// compile this with something like `go build -buildmode=plugin`

package main

import (
	"github.com/xen0n/gosmopolitan"
	"golang.org/x/tools/go/analysis"
)

type analyzerPlugin struct{}

func (analyzerPlugin) GetAnalyzers() []*analysis.Analyzer {
	// You can customize the options via gosmopolitan.NewAnalyzerWithConfig
	// instead.
	return []*analysis.Analyzer{
		gosmopolitan.DefaultAnalyzer,
	}
}

var AnalyzerPlugin analyzerPlugin

You just need to make sure the golang.org/x/tools version used to build the plugin is consistent with that of your golangci-lint binary. (Of course the golangci-lint binary should be built with plugin support enabled too; notably, the Homebrew golangci-lint is built without plugin support, so beware of this.)

golangci-lint version	gosmopolitan tag to use
1.50.x	v1.0.0

Then reference it in your .golangci.yml, and enable it in the linters section:

linters:
  # ...
  enable:
    # ...
    - gosmopolitan
    # ...

linters-settings:
  custom:
    gosmopolitan:
      path: 'path/to/your/plugin.so'
      description: 'Report certain i18n/l10n anti-patterns in your Go codebase'
      original-url: 'https://github.com/xen0n/gosmopolitan'
  # ...

Then you can golangci-lint run and //nolint:gosmopolitan as you would with any other supported linter.

License

gosmopolitan is licensed under the GPL license, version 3 or later.

Documentation

Index

• Variables
• func NewAnalyzer() *analysis.Analyzer
• func NewAnalyzerWithConfig(cfg *AnalyzerConfig) *analysis.Analyzer
• type AnalyzerConfig

Variables

var DefaultAnalyzer = NewAnalyzer()

Functions

func NewAnalyzer

func NewAnalyzer() *analysis.Analyzer

func NewAnalyzerWithConfig

func NewAnalyzerWithConfig(cfg *AnalyzerConfig) *analysis.Analyzer

Types

type AnalyzerConfig

type AnalyzerConfig struct {
	// LookAtTests is flag controlling whether the lints are going to look at
	// test files, despite other config knobs of the Go analysis tooling
	// framework telling us otherwise.
	//
	// By default gosmopolitan does not look at test files, because i18n-aware
	// apps most probably have many unmarked strings in test cases, and names
	// and descriptions *of* test cases are probably in the program's original
	// natural language too.
	LookAtTests bool
	// EscapeHatches is optionally a list of fully qualified names, in the
	// `(full/pkg/path).name` form, to act as "i18n escape hatches". Inside
	// call-like expressions to those names, the string literal script check
	// is ignored.
	//
	// With this functionality in place, you can use type aliases like
	// `type R = string` as markers, or have explicitly i18n-aware functions
	// exempt from the checks.
	EscapeHatches []string
	// WatchForScripts is optionally a list of Unicode script names to watch
	// for any usage in string literals. The range of supported scripts is
	// determined by the [unicode.Scripts] map and values are case-sensitive.
	WatchForScripts []string
	// AllowTimeLocal is flag controlling whether usages of [time.Local] are
	// allowed (i.e. not reported).
	AllowTimeLocal bool
}