Merge pull request #5 from donseba/tweaks

Tweaks and language file creation

Author: donseba

README.md

@@ -82,13 +82,50 @@ Localizer interface {
 ``` 
 
 
-Adding a New Language
+Setting a language to use
 --
 ```go
-tr.AddLanguage("en_US")
-tr.AddLanguage("nl_NL")
+tr.SetLanguage("en_US")
+tr.SetLanguage("nl_NL")
 ```
 
+Setting and possibly creating a New Language
+---------------------
+
+To add or ensure a language file exists (and is loaded), use the `EnsureLanguage` method. This will create a new `.po` file with the correct header (including plural forms) if it does not exist, and then load it into the translator:
+
+```go
+err := tr.EnsureLanguage("fr") // creates fr.po if missing, with correct header
+if err != nil {
+    log.Fatal(err)
+}
+```
+
+- The generated `.po` file will always include the recommended headers:
+  - `Content-Type: text/plain; charset=UTF-8`
+  - `Content-Transfer-Encoding: 8bit`
+  - `Plural-Forms` (auto-filled from plural rules)
+  - `Language` (set to the language code)
+
+- Calling `EnsureLanguage` multiple times is safe and will not overwrite existing files or translations.
+
+Testing and Idempotency
+-----------------------
+
+- The package includes tests to ensure that language files are created with the correct headers and that repeated calls to `EnsureLanguage` do not overwrite existing files.
+- Plural rules are generated from `plurals.json` and included in the codebase for accuracy and maintainability.
+
+Updating Plural Rules
+---------------------
+
+If you update `plurals.json`, regenerate the plural rules Go map by running:
+
+```sh
+go run tools/generate_templates.go
+```
+
+This will update `generated_plural_templates.go` with the latest plural forms and language codes.
+
 Scanning for Missing Translations
 --
 To check for missing translations in your templates:
@@ -108,6 +145,8 @@ tr.SetPrefixSeparator("__CUSTOM__")
 ```
 The default prefix separator is `__.`
 
+> **Note/Disclaimer:** While customizing the prefix separator is supported, it is generally recommended to use the CTL or CTN methods instead. These methods allow you to set translation context explicitly, which is more robust and flexible for handling similar keys in different contexts.
+
 Removing Prefixes from Translations
 --
 The package automatically handles the removal of prefixes from translations at runtime:

file_templates.go

@@ -0,0 +1,155 @@
+package translator
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"time"
+)
+
+// POT/PO file header template struct
+// You can expand this struct as needed for more fields
+// See: https://www.gnu.org/software/gettext/manual/html_node/Header-Entry.html
+
+type TranslationFileHeader struct {
+	ProjectID               string
+	ReportMsgidBugsTo       string
+	POTCreationDate         string
+	PORevisionDate          string
+	LastTranslator          string
+	LanguageTeam            string
+	Language                string
+	MIMEVersion             string
+	ContentType             string
+	ContentTransferEncoding string
+	PluralForms             string
+}
+
+// DefaultHeader returns a default header for a given language
+func DefaultHeader(language string) TranslationFileHeader {
+	now := time.Now().Format("2006-01-02 15:04-0700")
+	return TranslationFileHeader{
+		ProjectID:               "PACKAGE VERSION",
+		ReportMsgidBugsTo:       "",
+		POTCreationDate:         now,
+		PORevisionDate:          now,
+		LastTranslator:          "",
+		LanguageTeam:            "",
+		Language:                language,
+		MIMEVersion:             "1.0",
+		ContentType:             "text/plain; charset=UTF-8",
+		ContentTransferEncoding: "8bit",
+		PluralForms:             "nplurals=2; plural=(n != 1);",
+	}
+}
+
+// GetHeaderForLanguage returns a header template for a given language, falling back to DefaultHeader
+func GetHeaderForLanguage(language string) TranslationFileHeader {
+	if h, ok := LanguageHeaderTemplates[language]; ok {
+		h.ProjectID = "Go-FORM"
+		h.POTCreationDate = time.Now().Format("2006-01-02 15:04-0700")
+		h.PORevisionDate = h.POTCreationDate
+		h.LanguageTeam = "Go-FORM"
+		h.Language = language
+		h.ContentType = "text/plain; charset=UTF-8"
+		h.ContentTransferEncoding = "8bit"
+		return h
+	}
+	return DefaultHeader(language)
+}
+
+// WritePOTFile creates a POT file with the default header if it does not exist
+func WritePOTFile(path string) error {
+	if _, err := os.Stat(path); err == nil {
+		return nil // file exists
+	}
+	h := DefaultHeader("")
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	_, err = f.WriteString(h.HeaderString())
+	return err
+}
+
+// WritePOFile creates a PO file for a language with the default header if it does not exist
+func WritePOFile(path, language string) error {
+	if _, err := os.Stat(path); err == nil {
+		return nil // file exists
+	}
+	h := DefaultHeader(language)
+	f, err := os.Create(path)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	_, err = f.WriteString(h.HeaderString())
+	return err
+}
+
+// HeaderString returns the formatted header for a PO/POT file
+func (h TranslationFileHeader) HeaderString() string {
+	// Ensure Language is always set and not empty
+	lang := h.Language
+	if lang == "" {
+		lang = "C"
+	}
+	return fmt.Sprintf(`msgid ""
+msgstr ""
+"Project-Id-Version: %s\n"
+"Report-Msgid-Bugs-To: %s\n"
+"POT-Creation-Date: %s\n"
+"PO-Revision-Date: %s\n"
+"Last-Translator: %s\n"
+"Language-Team: %s\n"
+"Language: %s\n"
+"MIME-Version: %s\n"
+"Content-Type: %s\n"
+"Content-Transfer-Encoding: %s\n"
+"Plural-Forms: %s\n"
+`,
+		h.ProjectID,
+		h.ReportMsgidBugsTo,
+		h.POTCreationDate,
+		h.PORevisionDate,
+		h.LastTranslator,
+		h.LanguageTeam,
+		lang,
+		h.MIMEVersion,
+		h.ContentType,
+		h.ContentTransferEncoding,
+		h.PluralForms,
+	)
+}
+
+// GenerateLanguageHeaderTemplatesFromJSON parses a plurals.json file and generates Go code for LanguageHeaderTemplates
+func GenerateLanguageHeaderTemplatesFromJSON(jsonPath, goPath string) error {
+	data, err := os.ReadFile(jsonPath)
+	if err != nil {
+		return err
+	}
+	var plurals map[string]struct {
+		Name     string `json:"name"`
+		Formulas struct {
+			Standard string `json:"standard"`
+			PHP      string `json:"php"`
+		} `json:"formulas"`
+		Plurals int `json:"plurals"`
+	}
+	if err := json.Unmarshal(data, &plurals); err != nil {
+		return err
+	}
+
+	out := "package translator\n\n// Code generated by script. DO NOT EDIT.\n\nvar LanguageHeaderTemplates = map[string]TranslationFileHeader{\n"
+	for code, v := range plurals {
+		pluralForms := "nplurals=" + itoa(v.Plurals) + "; plural=(" + v.Formulas.Standard + ");"
+		out += "\t\"" + code + "\": {PluralForms: \"" + pluralForms + "\", Language: \"" + code + "\"},\n"
+	}
+	out += "}\n"
+	return os.WriteFile(goPath, []byte(out), 0644)
+}
+
+func itoa(i int) string {
+	return fmt.Sprintf("%d", i)
+}