docs: prefer string codes over integers in examples and docs

- Updated README and examples to use descriptive string identifiers (e.g., USER_CREATED, ERR_NOT_FOUND)
- Updated tests and test resources to use string codes
- Refined documentation to recommend strings for better self-documentation

Author: cmelgarejo

README.md

@@ -46,7 +46,7 @@ default:
   long: Unexpected message was received and was not found in this catalog
 set:
   greeting.hello:
-    code: 1
+    code: GREETING_HELLO
     short: User created
     long: User {{name}} was created successfully
   items.count:
@@ -64,6 +64,7 @@ default:
   long: Se recibió un mensaje inesperado y no se encontró en el catálogo
 set:
   greeting.hello:
+    code: GREETING_HELLO
     short: Usuario creado
     long: Usuario {{name}} fue creado correctamente
   items.count:
@@ -98,7 +99,7 @@ ctx := context.WithValue(context.Background(), "language", "es-AR")
 msg := catalog.GetMessageWithCtx(ctx, "greeting.hello", msgcat.Params{"name": "juan"})
 fmt.Println(msg.ShortText) // "Usuario creado"
 fmt.Println(msg.LongText)  // "Usuario juan fue creado correctamente"
-fmt.Println(msg.Code)      // "1" (from YAML optional code; Code is string)
+fmt.Println(msg.Code)      // "GREETING_HELLO" (from YAML optional code; Code is string)
 
 params := msgcat.Params{"count": 3, "amount": 12345.5, "when": time.Now()}
 err := catalog.WrapErrorWithCtx(ctx, errors.New("db timeout"), "items.count", params)
@@ -268,11 +269,11 @@ After translators fill `translate.es.yaml`, rename or copy it to `es.yaml` for r
 Many projects already use **error or message codes** (HTTP statuses, legacy numeric codes, string identifiers like `ERR_NOT_FOUND`). The optional **`code`** field in the catalog lets you **store that value** with each message and have it returned in `Message.Code` and `ErrorCode()` so your API can expose it unchanged.
 
 - **Optional** — You can omit `code` entirely. When empty, use `Message.Key` or `ErrorKey()` as the stable identifier for clients (e.g. in JSON: `"error_code": msg.Code or msg.Key`).
-- **Any value** — Codes are strings. In YAML you can write `code: 404` (parsed as `"404"`) or `code: "ERR_NOT_FOUND"`. In Go use `msgcat.CodeInt(503)` or `msgcat.CodeString("ERR_MAINT")`.
+- **Any value** — Codes are strings. In YAML you can write `code: ERR_NOT_FOUND` or `code: "404"`. In Go use `msgcat.CodeString("ERR_MAINT")` or `msgcat.CodeInt(503)`.
 - **Not unique** — The catalog does not require codes to be unique. If your design uses the same code for several messages (e.g. same HTTP status for different keys), you can repeat the same `code` value.
 - **Your identifier** — The catalog never interprets the code; it only stores and returns it. You decide what values to use and how to expose them in your API.
 
-**When to set a code:** Use it when you need a stable, project-specific value to return to clients (status codes, error enums, etc.). When you don’t, leave it unset and use the message **key** as the identifier.
+**When to set a code:** Use it when you need a stable, project-specific value to return to clients (status codes, error enums, etc.). Strings are generally preferred over integers as they are more descriptive (e.g., `code: ERR_ACCESS_DENIED` instead of `code: 403`). When you don’t need a separate code, leave it unset and use the message **key** as the identifier.
 
 Helpers for building `RawMessage.Code` in code: `msgcat.CodeInt(503)`, `msgcat.CodeString("ERR_NOT_FOUND")`.
 

docs/CONVERSION_PLAN.md

@@ -92,7 +92,7 @@ set:
     short: Hello short description
     long: Hello veeery long description.
   greeting.template:
-    code: 1002   # optional (stored as string; see §12)
+    code: GREETING   # optional (stored as string; see §12)
     short: Hello template {{name}}, this is nice {{detail}}
     long: Hello veeery long {{name}} description. Details {{detail}}.
   items.count:

examples/basic/main.go

@@ -24,15 +24,15 @@ func main() {
   long: Message not found in catalog
 set:
   greeting.hello:
-    code: 1
+    code: GREETING
     short: Hello
     long: Hello, welcome.
   greeting.template:
-    code: 2
+    code: WELCOME
     short: Hello {{name}}, role {{role}}
     long: Hello {{name}}, you are {{role}}.
   error.gone:
-    code: 404
+    code: NOT_FOUND
     short: Not found
     long: Resource not found.
 `)

examples/load_messages/main.go

@@ -40,7 +40,7 @@ set:
 			Key:      "sys.maintenance",
 			ShortTpl: "Under maintenance",
 			LongTpl:  "Back in {{minutes}} minutes.",
-			Code:     msgcat.CodeInt(503), // or msgcat.CodeString("ERR_MAINTENANCE")
+			Code:     msgcat.CodeString("ERR_MAINTENANCE"),
 		},
 	})
 	if err != nil {

examples/msgdef/main.go

@@ -31,7 +31,7 @@ var (
 		Key:   "items.count",
 		Short: "{{count}} items",
 		Long:  "Total: {{count}} items",
-		Code:  msgcat.CodeInt(200),
+		Code:  msgcat.CodeString("OK"),
 	}
 )
 
@@ -57,7 +57,7 @@ set:
   items.count:
     short: "{{count}} items"
     long: "Total: {{count}} items"
-    code: 200
+    code: OK
 `)
 	if err := os.WriteFile(filepath.Join(dir, "en.yaml"), en, 0o600); err != nil {
 		panic(err)

test/suites/msgcat/msgcat_test.go

@@ -81,7 +81,7 @@ var _ = Describe("Message Catalog", func() {
 
 	It("should return message code", func() {
 		message := messageCatalog.GetMessageWithCtx(ctx.Ctx, "greeting.hello", nil)
-		Expect(message.Code).To(Equal("1"))
+		Expect(message.Code).To(Equal("GREETING_HELLO"))
 	})
 
 	It("should set Message.Key and use Key when Code is empty for API identifier", func() {
@@ -171,15 +171,15 @@ var _ = Describe("Message Catalog", func() {
 		castedError := err.(msgcat.Error)
 		Expect(castedError.GetShortMessage()).To(Equal("Hola, breve descripción"))
 		Expect(castedError.GetLongMessage()).To(Equal("Hola, descripción muy larga. Solo puedes verme en la página de detalles."))
-		Expect(castedError.ErrorCode()).To(Equal("1"))
+		Expect(castedError.ErrorCode()).To(Equal("GREETING_HELLO"))
 	})
 
 	It("should be able to load messages from code", func() {
 		err := messageCatalog.LoadMessages("en", []msgcat.RawMessage{{
 			Key:      "sys.9001",
 			LongTpl:  "Some long system message",
 			ShortTpl: "Some short system message",
-			Code:     msgcat.CodeInt(9001),
+			Code:     msgcat.CodeString("SYS_ERR"),
 		}})
 		Expect(err).NotTo(HaveOccurred())
 		err = messageCatalog.GetErrorWithCtx(ctx.Ctx, "sys.9001", nil)
@@ -191,7 +191,7 @@ var _ = Describe("Message Catalog", func() {
 			Key:      "sys.9001",
 			LongTpl:  "Mensagem longa de sistema",
 			ShortTpl: "Mensagem curta de sistema",
-			Code:     msgcat.CodeInt(9001),
+			Code:     msgcat.CodeString("SYS_ERR"),
 		}})
 		Expect(err).NotTo(HaveOccurred())
 
@@ -218,7 +218,7 @@ var _ = Describe("Message Catalog", func() {
 			Key:      "sys.loaded",
 			LongTpl:  "Loaded from code",
 			ShortTpl: "Loaded from code short",
-			Code:     msgcat.CodeInt(9001),
+			Code:     msgcat.CodeString("SYS_ERR"),
 		}})
 		Expect(err).NotTo(HaveOccurred())
 		Expect(customCatalog.GetMessageWithCtx(ctx.Ctx, "sys.loaded", nil).ShortText).To(Equal("Loaded from code short"))
@@ -350,7 +350,7 @@ var _ = Describe("Message Catalog", func() {
 			Key:      "sys.runtime",
 			LongTpl:  "Runtime long",
 			ShortTpl: "Runtime short",
-			Code:     msgcat.CodeInt(9001),
+			Code:     msgcat.CodeString("SYS_ERR"),
 		}})
 		Expect(err).NotTo(HaveOccurred())
 
@@ -528,7 +528,7 @@ var _ = Describe("Message Catalog", func() {
 					Key:      key,
 					LongTpl:  fmt.Sprintf("Long %s", key),
 					ShortTpl: fmt.Sprintf("Short %s", key),
-					Code:     msgcat.CodeInt(9000 + i),
+					Code:     msgcat.CodeString(fmt.Sprintf("ERR_%d", i)),
 				}})
 				if err != nil {
 					errCh <- err

test/suites/msgcat/resources/messages/en.yaml

@@ -3,7 +3,7 @@ default:
   long: Unexpected error was received and was not found in catalog
 set:
   greeting.hello:
-    code: 1
+    code: GREETING_HELLO
     short: Hello short description
     long: Hello veeery long description. You can only see me in details page.
   greeting.template:

test/suites/msgcat/resources/messages/es.yaml

@@ -3,7 +3,7 @@ default:
   long: Se recibió un error inesperado y no se encontró en el catálogo!
 set:
   greeting.hello:
-    code: 1
+    code: GREETING_HELLO
     short: Hola, breve descripción
     long: Hola, descripción muy larga. Solo puedes verme en la página de detalles.
   items.count: