android

Documentation

Overview

Package android implements reading and writing of Android strings.xml translation files.

Supported resource types:

• <string> — simple key/value string
• <string-array> — ordered list of strings
• <plurals> — quantity-keyed plural forms (zero/one/two/few/many/other)

Resources with translatable="false" are parsed but excluded from all translation-related accessors (Keys, UntranslatedKeys, SyncKeys, etc.). They are still written back verbatim on Marshal.

Index

• func AndroidLocaleDirName(lang string) string
• func DetectLanguages(resDir string) []string
• func SourceStringsXMLPath(resDir string) string
• func StringsXMLPath(resDir, lang string) string
• type Entry
  • func (e *Entry) IsComment() bool
  • func (e *Entry) IsTranslatable() bool
  • func (e *Entry) IsTranslated() bool
• type EntryKind
• type File
  • func NewTranslationFile(source *File) *File
  • func Parse(data []byte) (*File, error)
  • func ParseFile(path string) (*File, error)
  • func (f *File) Get(name string) (string, bool)
  • func (f *File) GetEntry(name string) *Entry
  • func (f *File) Keys() []string
  • func (f *File) Marshal() []byte
  • func (f *File) MarshalTarget() []byte
  • func (f *File) Set(name, value string) bool
  • func (f *File) SetItems(name string, items []string) bool
  • func (f *File) SetPlurals(name string, forms map[string]string) bool
  • func (f *File) Stats() (total, translated, untranslated int)
  • func (f *File) SyncKeys(source *File) int
  • func (f *File) UntranslatedEntries() []*Entry
  • func (f *File) UntranslatedKeys() []string
  • func (f *File) WriteFile(path string) error
  • func (f *File) WriteTargetFile(path string) error

Functions

func AndroidLocaleDirName

func AndroidLocaleDirName(lang string) string

AndroidLocaleDirName converts a standard language code to an Android values directory name (e.g., "pt-BR" -> "values-pt-rBR", "ru" -> "values-ru").

func DetectLanguages

func DetectLanguages(resDir string) []string

DetectLanguages scans an Android res/ directory for values-XX/ directories that contain strings.xml and returns the language codes.

func SourceStringsXMLPath

func SourceStringsXMLPath(resDir string) string

SourceStringsXMLPath returns the path to the default (source) strings.xml.

func StringsXMLPath

func StringsXMLPath(resDir, lang string) string

StringsXMLPath returns the path to strings.xml for a given language.

Types

type Entry

type Entry struct {
	// Kind is the resource type.
	Kind EntryKind

	// Name is the resource name (attribute name="…"). Empty for comments.
	Name string
	// Translatable reflects the translatable="…" attribute. Defaults to true.
	Translatable bool

	// Value is the translated text. Empty means untranslated.
	// Apostrophes are stored unescaped (\'  →  ') for clean LLM input;
	// they are re-escaped on Marshal.
	Value string
	// UseCDATA indicates the source value was wrapped in <![CDATA[...]]>.
	// When true, Marshal emits CDATA instead of XML-escaping the value.
	UseCDATA bool

	// Items holds the <item> values in document order (apostrophes unescaped).
	Items []string
	// ItemCDATA mirrors Items: true when the corresponding <item> used CDATA.
	ItemCDATA []bool

	// Plurals maps quantity keyword (zero/one/two/few/many/other) to text
	// (apostrophes unescaped).
	Plurals map[string]string
	// PluralOrder preserves the order of quantity keywords as they appear in the file.
	PluralOrder []string
	// PluralCDATA mirrors PluralOrder: true when the corresponding <item> used CDATA.
	PluralCDATA map[string]bool

	// Comment is the raw comment text (without <!-- -->). Empty for resources.
	Comment string
}

Entry represents a single item in a strings.xml file. It may be a string resource, a string-array, a plurals block, or a comment.

func (*Entry) IsComment

func (e *Entry) IsComment() bool

IsComment reports whether this entry is an XML comment.

func (*Entry) IsTranslatable

func (e *Entry) IsTranslatable() bool

IsTranslatable reports whether this resource should be translated.

func (*Entry) IsTranslated

func (e *Entry) IsTranslated() bool

IsTranslated reports whether the entry has a complete (non-empty) translation.

type EntryKind

type EntryKind int

EntryKind identifies the type of a resource entry.

const (
	// KindString is a plain <string> resource.
	KindString EntryKind = iota
	// KindStringArray is a <string-array> resource.
	KindStringArray
	// KindPlurals is a <plurals> resource.
	KindPlurals
	// KindComment is an XML comment (not a resource).
	KindComment
)

type File

type File struct {
	// Entries in document order (resources + comments).
	Entries []*Entry
	// contains filtered or unexported fields
}

File represents a parsed Android strings.xml file.

func NewTranslationFile

func NewTranslationFile(source *File) *File

NewTranslationFile creates a new File with the same structure as source but with all translatable values empty (untranslated). Non-translatable entries are copied verbatim; comments are preserved.

func Parse

func Parse(data []byte) (*File, error)

Parse parses Android strings.xml data.

func ParseFile

func ParseFile(path string) (*File, error)

ParseFile reads and parses an Android strings.xml file.

func (*File) Get

func (f *File) Get(name string) (string, bool)

Get returns the string value for a KindString entry. Returns ("", false) for non-string entries or missing keys.

func (*File) GetEntry

func (f *File) GetEntry(name string) *Entry

GetEntry returns the entry for a given resource name, or nil if not found.

func (*File) Keys

func (f *File) Keys() []string

Keys returns all translatable resource names in document order.

func (*File) Marshal

func (f *File) Marshal() []byte

Marshal produces the XML output in Android strings.xml format. isSource should be true when writing the default values/strings.xml — in that case non-translatable resources are included verbatim. For target locale files (values-XX/strings.xml) pass isSource=false to omit them.

func (*File) MarshalTarget

func (f *File) MarshalTarget() []byte

MarshalTarget produces the XML for a translated locale file, omitting resources marked translatable="false" (they live only in the source file).

func (*File) Set

func (f *File) Set(name, value string) bool

Set sets the string value for a KindString entry. Returns false if the key doesn't exist or is not a KindString.

func (*File) SetItems

func (f *File) SetItems(name string, items []string) bool

SetItems sets the items for a KindStringArray entry. Returns false if the key doesn't exist or is not a KindStringArray.

func (*File) SetPlurals

func (f *File) SetPlurals(name string, forms map[string]string) bool

SetPlurals sets the plural forms for a KindPlurals entry. Returns false if the key doesn't exist or is not a KindPlurals.

func (*File) Stats

func (f *File) Stats() (total, translated, untranslated int)

Stats returns (total, translated, untranslated) counts for translatable resources.

func (*File) SyncKeys

func (f *File) SyncKeys(source *File) int

SyncKeys ensures the translation file has all translatable keys from source. Missing keys are added with empty values (preserving kind and structure). Non-translatable entries and comments are not synced. Returns the number of keys added.

func (*File) UntranslatedEntries

func (f *File) UntranslatedEntries() []*Entry

UntranslatedEntries returns translatable entries that have no complete translation.

func (*File) UntranslatedKeys

func (f *File) UntranslatedKeys() []string

UntranslatedKeys returns names of translatable entries that have no complete translation.

func (*File) WriteFile

func (f *File) WriteFile(path string) error

WriteFile writes the strings.xml file to disk as a source file (includes all entries, including translatable="false").

func (*File) WriteTargetFile

func (f *File) WriteTargetFile(path string) error

WriteTargetFile writes the strings.xml file for a translated locale. Resources marked translatable="false" are omitted — Android inherits them from the default values/strings.xml automatically.