Skip to content

Conversation

@cxjava
Copy link

@cxjava cxjava commented Jan 12, 2026

Summary

Add FastParser as an alternative template parser using valyala/fasttemplate, primarily for TinyGo compatibility.

Motivation

TinyGo has limited support for the standard library's text/template and html/template packages due to their heavy use of reflection and other features that are difficult to compile to WebAssembly or embedded targets. This makes go-i18n unusable in TinyGo environments when templates contain placeholders.

FastParser provides a lightweight alternative that works reliably in TinyGo while still supporting the common use case of simple placeholder substitution.

Changes

  • Add FastParser implementing template.Parser interface
  • Add comprehensive unit tests for FastParser
  • Add integration tests in localizer_test.go
  • Add github.com/valyala/fasttemplate dependency

Usage

localizer.Localize(&i18n.LocalizeConfig{
    DefaultMessage: &i18n.Message{
        ID:    "HelloPerson",
        One:   "{{.Name}} has {{.Count}} cat",
        Other: "{{.Name}} has {{.Count}} cats",
    },
    TemplateData: map[string]interface{}{
        "Name":  "Nick",
        "Count": 2,
    },
    PluralCount:    2,
    TemplateParser: &template.FastParser{},  // Use FastParser
})

Supported Features

  • Simple placeholder substitution: {{.Key}} and {{Key}}
  • Custom delimiters (e.g., << >>)
  • Data types: map[string]interface{}, map[string]string, and structs
  • All plural forms (Zero, One, Two, Few, Many, Other)
  • Missing keys preserve the original placeholder

Limitations

For these features, continue using TextParser:

  • Template functions (e.g., {{printf "%s" .Name}})
  • Conditionals (e.g., {{if .Cond}}...{{end}})
  • Range loops (e.g., {{range .Items}}...{{end}})
  • Nested field access (e.g., {{.User.Name}})
  • Method calls (e.g., {{.Name.String}})

Benchmark

BenchmarkFastParser_Execute-14    249.3 ns/op    368 B/op    10 allocs/op
BenchmarkTextParser_Execute-14    263.1 ns/op    336 B/op     9 allocs/op

FastParser is slightly faster (~5%) for simple placeholder substitution.

Add FastParser as an alternative template parser using valyala/fasttemplate.
This provides TinyGo compatibility since text/template has limited support
in TinyGo due to heavy reflection usage.

FastParser supports:
- Simple placeholder substitution: {{.Key}} and {{Key}}
- Custom delimiters
- map[string]interface{}, map[string]string, and struct data types
- Plural forms (One, Other, etc.)

Limitations (use TextParser instead):
- Template functions
- Conditionals (if/else)
- Range loops
- Nested field access
- Method calls
@codecov
Copy link

codecov bot commented Jan 12, 2026

Codecov Report

❌ Patch coverage is 75.75758% with 24 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.24%. Comparing base (4d19ec6) to head (50e3968).

Files with missing lines Patch % Lines
i18n/template/fast_parser.go 75.75% 17 Missing and 7 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #400      +/-   ##
==========================================
+ Coverage   73.97%   74.24%   +0.26%     
==========================================
  Files          20       21       +1     
  Lines        1679     1778      +99     
==========================================
+ Hits         1242     1320      +78     
- Misses        376      389      +13     
- Partials       61       69       +8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant