docs: readme for i18n card builder [ci skip]

Author: crispgm

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v1.10.0
+
+- feat(im): support card with i18n (#59)
+
 ## v1.9.0
 
 - feat(im): support column set (#57)

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018-2022 go-lark
+Copyright (c) 2018-2023 go-lark
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -140,10 +140,10 @@ Here is a collection of ready-to-run examples for each part of `go-lark`:
 
 - [examples/auth](https://github.com/go-lark/examples/tree/main/auth)
 - [examples/basic-message](https://github.com/go-lark/examples/tree/main/basic-message)
-- [examples/image-message](https://github.com/go-lark/examples/tree/main/image-message)
 - [examples/rich-text-message](https://github.com/go-lark/examples/tree/main/rich-text-message)
-- [examples/share-chat](https://github.com/go-lark/examples/tree/main/share-chat)
 - [examples/interactive-message](https://github.com/go-lark/examples/tree/main/interactive-message)
+- [examples/image-message](https://github.com/go-lark/examples/tree/main/image-message)
+- [examples/share-chat](https://github.com/go-lark/examples/tree/main/share-chat)
 - [examples/group](https://github.com/go-lark/examples/tree/main/group)
 
 ### Message Buffer
@@ -380,4 +380,4 @@ func CopyFile(bot *lark.Bot, fileToken, dstFolderToken, dstName string) (*CopyFi
 
 ## License
 
-Copyright (c) David Zhang, 2018-2022. Licensed under MIT License.
+Copyright (c) David Zhang, 2018-2023. Licensed under MIT License.

README_zhCN.md

@@ -131,10 +131,10 @@ resp, err := bot.GetTenantAccessTokenInternal(true)
 
 - [鉴权](https://github.com/go-lark/examples/tree/main/auth)
 - [基本消息](https://github.com/go-lark/examples/tree/main/basic-message)
-- [图片消息](https://github.com/go-lark/examples/tree/main/image-message)
 - [富文本消息](https://github.com/go-lark/examples/tree/main/rich-text-message)
-- [分享群卡片](https://github.com/go-lark/examples/tree/main/share-chat)
 - [交互卡片](https://github.com/go-lark/examples/tree/main/interactive-message)
+- [图片消息](https://github.com/go-lark/examples/tree/main/image-message)
+- [分享群卡片](https://github.com/go-lark/examples/tree/main/share-chat)
 - [群操作](https://github.com/go-lark/examples/tree/main/group)
 
 ### Message Buffer
@@ -145,9 +145,14 @@ MsgBuffer 支持多种类型的消息：
 
 - `MsgText`：文本
 - `MsgPost`：富文本
-- `MsgImage`：图片
-- `MsgShareCard`：群名片
 - `MsgInteractive`：交互式卡片
+- `MsgShareUser`: 用户名片
+- `MsgShareCard`：群名片
+- `MsgImage`：图片
+- `MsgFile`: 文件
+- `MsgAudio`: 音频
+- `MsgMedia`: 媒体
+- `MsgSticker`: 表情
 
 MsgBuffer 主要有两类函数，Bind 函数和内容函数。
 
@@ -362,4 +367,4 @@ func CopyFile(bot *lark.Bot, fileToken, dstFolderToken, dstName string) (*CopyFi
 
 ## 协议
 
-Copyright (c) David Zhang, 2018-2022. Licensed under MIT License.
+Copyright (c) David Zhang, 2018-2023. Licensed under MIT License.

card/README.md

@@ -2,6 +2,11 @@
 
 Interactive card is rich in formats. However, it takes much efforts to build one. Thus, we provide a declarative card builder to make it easier.
 
+We map every element of card (`div`, `text`, `button`, etc.) to declarative calls as shown in the demo.
+
+All inner elements (e.g. `fields` of `div` blocks) are considered as arguments,
+while all element properties (e.g. `forward` property of `card` blocks) are considered as chained calls.
+
 ## Getting Started
 
 ```go
@@ -38,17 +43,33 @@ which will render as following:
 }
 ```
 
-We map every element of card (`div`, `text`, `button`, etc.) to declarative calls as shown in the demo.
-
-All inner elements (e.g. `fields` of `div` blocks) are considered as arguments,
-while all element properties (e.g. `forward` property of `card` blocks) are considered as chained calls.
+Example: [examples/interactive-message](https://github.com/go-lark/examples/tree/main/interactive-message)
 
-Refer to [msg_card_builder_test.go](./msg_card_builder_test.go) for details.
+## I18N
 
-## Limits
+Card with I18N support is also supported. We introduce a `I18N` struct to build localizable parts (e.g. title and contents):
 
-- i18n cards are currently NOT YET SUPPORTED. Use raw json if necessary.
-- `CardBuilder` contains ONLY a group of card-builder-related functions and contains NO card content. Thus, you can use the same `CardBuilder` whenever building a card instead of making a new one before build.
+```go
+b := lark.NewCardBuilder()
+c := b.I18N.Card(
+        b.I18N.WithLocale(
+            LocaleEnUS,
+            b.Div(
+                b.Field(b.Text("English Content")),
+            ),
+        ),
+        b.I18N.WithLocale(
+            LocaleZhCN,
+            b.Div(
+                b.Field(b.Text("中文内容")),
+            ),
+        ),
+    ).
+    Title(
+        b.I18N.LocalizedText(LocaleEnUS, "English Title"),
+		b.I18N.LocalizedText(LocaleZhCN, "中文标题"),
+    )
+```
 
 ## Sending Message
 

card/README_zhCN.md

@@ -1,9 +1,15 @@
-# 声明式卡片构造工具
+# 卡片构造工具
+
+交互卡片是飞书消息中比较受欢迎的交互形式，但构造起来比较复杂，因此我们提供了专门的卡片构造工具。
+
+卡片构造工具采用声明式 API 设计，我们把每一个元素（`div`、`text`、`button` 等）都映射成声明的形式。
+
+我们约定使用「参数」来表示**元素内部**的子元素（例如 `div` 中的 `fields`），用「链式调用」来设置**元素本身**的属性（例如卡片中的 `forward`）。
 
 ## 使用方式
 
 ```go
-b := NewCardBuilder()
+b := lark.NewCardBuilder()
 c := b.Card(
     b.Markdown("some text"),
 ).
@@ -36,23 +42,39 @@ fmt.Println(c.String())
 }
 ```
 
-我们把每一个元素（`div`、`text`、`button` 等）都映射成这样的声明形式。
+参考实例：[交互卡片](https://github.com/go-lark/examples/tree/main/interactive-message)
 
-我们约定使用「参数」来表示**元素内部**的子元素（例如 `div` 中的 `fields`），用「链式调用」来设置**元素本身**的属性（例如卡片中的 `forward`）。
-
-详细请参见[msg_card_builder_test.go](./msg_card_builder_test.go)。
+## 国际化支持
 
-## 限制
+我们也支持构造多语言的卡片，在标题和内容等特定部分，需要引用 `I18N` 结构中的方法构造：
 
-- 暂不支持 i18n 卡片，如有相关需求请暂时使用 json
-- `CardBuilder` 只作为卡片构造相关方法的集合，不具备承载卡片的功能，所以你可以在任意地方使用同一个 `CardBuilder` ，无需每次使用前新建。
+```go
+b := lark.NewCardBuilder()
+c := b.I18N.Card(
+        b.I18N.WithLocale(
+            LocaleEnUS,
+            b.Div(
+                b.Field(b.Text("English Content")),
+            ),
+        ),
+        b.I18N.WithLocale(
+            LocaleZhCN,
+            b.Div(
+                b.Field(b.Text("中文内容")),
+            ),
+        ),
+    ).
+    Title(
+        b.I18N.LocalizedText(LocaleEnUS, "English Title"),
+        b.I18N.LocalizedText(LocaleZhCN, "中文标题"),
+    )
+```
 
-## 使用 go-lark 发送
+## 发送
 
 ```go
 b := lark.NewCardBuilder()
 c := b.Card(...Elements)
-// 使用 c.String() 或者 c.MarshalJSON() 将卡片内容渲染为 string 或 []byte
 msg := lark.NewMsgBuffer(lark.MsgInteractive)
 om := msg.BindEmail("[email protected]").Card(c.String()).Build()
 bot.PostMessage(om)