---
# System prepended metadata

title: SpriteLocalizer (仮)
tags: [Creator3D]

---

# SpriteLocalizer (仮)

這個 class 的主要功能是能在 run time 時可以替換不同語言的圖片，只要輸入 node，就會偵測 node 下哪些圖片需要更換，並且從對應語言的圖集裡面將圖片更換。

## **SpriteLocalizer** 的前置作業

在專案的 **assets** 下新增 **resources** 資料夾，Cocos Creator 要動態載入資源必須要有這個資料夾
![](https://i.imgur.com/8ObLHWE.png)

在 resources 裡面再新增 config 與 sprites 的資料夾
![](https://i.imgur.com/HrP7Kzt.png)

config 資料夾裡放置多國語系 atlas path 資訊的 json 檔案(**local_atlas.json**)，而 json 內容如下所示
每個項目的 id 需要與 atlas 名稱一樣
```
[
  {
    "id": "black_gameScene",
    "zh_cn": "sprites/zh_cn/black/gameScene/black_gameScene",
    "zh_tw": "sprites/zh_tw/black/gameScene/black_gameScene",
    "en_us": "sprites/en_us/black/gameScene/black_gameScene"
  }
]
```

在 sprites 資料夾裡面放置不同語系的圖片資料，要替換多少種語系就產生多少個資料夾，在各自語系資料夾內根據分類放置圖片，一個 atlas 圖集的圖片要在同一個資料夾內
![](https://i.imgur.com/kzH7X2P.png)

打開 Cocos Creator 3D，在各自圖集資料夾內新增 [Auto Atlas](https://docs.cocos.com/creator3d/manual/zh/asset/auto-atlas.html) 的檔案，將產生的 Auto Atlas Path 填入 **local_atlas.json** 檔案
![](https://i.imgur.com/hWWqqrn.png)

**※** **Auto Atlas** 的 Inspector 裡有個 **Preview** 按鈕，可以觀看 atlas 打包之後的結果，但是並不會實際真的打包，**Auto Atlas** 在<font color=#f00>**執行 build 的時候**</font>才會真正的被打包，因此測試期間是無法取得 atlas 資料


## 使用**SpriteLocalizer**

在專案啟動時，為了在一開始將所有的 Atlas 檔案載入，需要優先執行
```
SpriteLocalizer.instance.init();
```
目前的語言設定還沒有地方可以存取，因此之後需要將以下程式碼更改
```
// TODO 要從其他地方拿到 lang 資訊
let lang: string = "zh_cn";
```

:::warning
雖然可以使用 isAtlasReady 檢查 local_atlas.json 裡面所有的 atlas 檔案是否都載入
但是目前 atlas 檔案量少，還要驗證是否需要用其他方式來等待或判斷 Ready
:::

目前只有開放兩個 Function 使用
```
/** 替換 root 下所有多語系相關 (spriteAtlas不為null) 的 sprite */
public refreshAllSprite(root: Node): void

/** 替換單一張多語系相關 (spriteAtlas不為null) 的 sprite */
public refreshSingleSprite(sprite: SpriteComponent): void
```
而在 Editor 的設定上，需要被更換多語系圖片的 Sprite，在 SpriteAtlas 欄位要選擇存放本身圖片的 Auto Atlas 檔案，語系不限；SpriteFrame 也要將顯示的圖片放入
![](https://i.imgur.com/KLcSS2f.png)

**※ 換圖片流程**
1. 先取得 node 下所有的 SpriteComponent，當 SpriteComponent 的 SpriteAtlas 欄位不為空時，先假定是需要換圖的 Sprite
2. 接著將 SpriteAtlas 的名稱與存放的 Atlas 資料庫比對，若有找到對應的 Atlas 便進行換圖作業
3. 最後根據 SpriteFrame 的 Sprite Name 在 Atlas 找到對應的 Sprite，將 SpriteFrame 替換。


###### tags: `Creator3D`