create-app

Crowdin アプリを作成する

依頼者について

翻訳者、またはローカライズマネージャーです。仕様書ではなく、うんざりしている作業を抱えてやってきます。「この用語を以前どう訳したか見せて」「私のあとで校正者がどこを変更したか確認したい」「毎週木曜日に、このスプレッドシートを手作業で作っています」。

モジュール、マニフェスト、スコープ、エディターモード、プロジェクト ID が何かを知らず、このプラットフォームでできること、できないことも知りません。自分のアイデアが実現可能かどうかを事前に確認することはありませんし、その必要もありません。**相手に尋ねることはすべて、コードを一行も見たことがない人でも答えられる質問でなければなりません。**モジュールの種類、スコープ、マニフェスト、テンプレート、エディターモード、プロジェクト ID、エディションについて尋ねるのは、このワークフローの欠陥であり、ユーザーの知識不足ではありません。

依頼がプラットフォームの制限を超えてしまった場合、それを解決するのはあなたの問題であり、依頼者が事前に避けるべき問題ではありません。プラットフォームが「いいえ」と言うときを参照してください。

実際に作成するもの

Crowdin が自社の UI 内の iframe に読み込む、フロントエンドのみの React バンドルです。アプリにバックエンドもトークンもありません。ホストが Crowdin REST の呼び出しを実行し、アプリの永続化されたレコード（アプリで情報を保持する必要がある場合の Crowdin Storage）を、アプリを開いたユーザーのセッション下で、マニフェストに宣言されたスコープの範囲内で保持します。

情報の参照元

プラットフォームには、時間とともにモジュールの種類、マニフェストのフィールド、SDK メソッド、スコープが追加されます。このスキルも、それを学習したデータも最新の状態を保てるとは限りません。そのため、存在する機能を確認するにはドキュメントを取得してください。すべてのページには機械可読な形式が用意されています。ドキュメントの URL の末尾に .md を追加するか、すべてのページをまとめて取得してください。

取得するもの	内容
building-app/modules.md	現在のモジュールの種類と prepare* 関数
reference/manifest.md	マニフェストのフィールド、モジュールの構造、権限
reference/cli-commands.md	リリース済みのコマンドとフラグ
building-app/crowdin-api.md	トークン不要の API クライアント
building-app/storage.md	Crowdin Storage — 永続化される共有レコード、ユーザーごとのレコード、モジュールスコープのレコード
building-app/context.md	コンテキスト、テーマ、イベント
building-app/host-actions.md	エディターとホストのアクション
building-app/user-interface.md	UI キット
building-app/i18n.md	ローカライズ
development/troubleshooting.md	既知の問題
understanding-scopes	各スコープで許可される内容
llms-full.txt	すべての情報を一度に取得

役割分担は次のとおりです。**何が存在するかについてはドキュメントが正式な情報源であり、どの順序で作業するか、何が問題を引き起こすかについてはこのスキルが案内します。**ここにある一覧とドキュメントの内容が異なる場合は、ドキュメントを優先してください。この一覧が古くなっている可能性があります。このページに記載がなくても、ドキュメントで説明されている機能を活用してください。機能は動作するものの、ドキュメントに記載されていない問題が起きる場合は、このスキルが役立ちます。

目指すゴール

ゴールは「コードを書いた」ことでも、「アプリを公開した」ことでもありません。ユーザーが動作するアプリを実際に見ていることです。表示されると確信できるリンクを渡すまでは、実行は未完了として扱ってください。リンクのない配置の場合は、ユーザーがアプリを確認できたと伝えるまで未完了です。

まず尋ねる価値がある唯一の質問

リンクを尋ねてください。

Crowdin のページへのリンクを送っていただけますか？作業中のプロジェクトでも、ホームページでも構いません。

誰でもアドレスバーから URL をコピーできます。URL があれば、通常は推測できない次の 2 つのことがわかります。

• エディション。 ホストが crowdin.com なら Crowdin、その他（<org>.crowdin.com）なら Crowdin Enterprise です。ユーザーが希望する配置がそもそも存在するかどうかが決まります。開ける 11 種類のモジュールのうち 6 種類は、いずれか一方のエディションにしかありません。
• プロジェクト。 crowdin.com/project/<identifier> または <org>.crowdin.com/u/projects/<id> から、preview --project に必要な値がわかります。「identifier」を尋ねる必要はありません。

リンクが送られなかった場合は、ログイン後の CLI 独自の状態ファイルにエディションが保存されています。場所は ~/.crowdin/serverless-apps-cli.json です。domain に値があれば Enterprise、なければ crowdin.com です。

スキャフォールディングの前に4つの項目を決める

項目	早めに決める必要がある理由
名前	create <name> はディレクトリ名を決め、アプリを登録し、UI 上でアプリとすべてのモジュールに名前を付けます。短いラテン文字のスラッグを渡してください。ユーザーが人に見せる名前を希望する場合は、その後マニフェストの name を設定してプッシュしてください。
配置	Crowdin UI のどこに表示するかです。間違えた場合の修正コストが最も高く、エディションによる制約もあります（modules.md）。
ロジック	ユーザーがどのような結果を見たいかです。UI と API 呼び出し、ひいては scopes を決めます。
誰に見えるか	default_permissions です。デフォルトでは owner のみになっており、ほとんどの依頼には適していません。また、後から対象を広げることはできません。表示範囲を参照してください。

質問は控えめに、ユーザーの言葉で

尋ねずに推測する: ユーザーが誰か、アプリがどのデータを扱うか、scopes（依頼内容の入力ではなく、承認ゲートの結果です。scopes.mdを参照）、エディションとプロジェクト（リンクから判断）、エディターの modes（デフォルトではドキュメントに記載されたすべてのモードを宣言してください。そうすれば、ユーザーが作業している場所を問わずパネルが表示されます。ユーザーから希望があった場合にのみ絞り込んでください。マニフェストに含まれないモードではモジュールがまったく表示されず、その理由をユーザーが知る手段もないためです）、適切なアプリ名。テンプレートは固定で、常に projects-dashboard-cli を使います。

尋ねずに提示する: 推測した内容をすべて短い概要にまとめ、ユーザーが修正できるようにします。ユーザーが話しかけてきた言語で、平易な言葉を使って書いてください。「エディターの右側、文字列の隣にパネル」のように表現し、「editor-right-panel, modes translate/review」のような書き方は避けます。主張を並べたほうが、質問を並べるよりも異議を唱えやすくなります。

次の場合にのみ質問する:

1. 依頼から配置が本当に判断できない場合。「エディターで文字列の隣」は決まっています。「プロジェクト内」だけでは、Tools セクションと Reports セクションのどちらに置くかという実質的な選択肢が残ります。配置場所として説明し、推奨案も添えて尋ねてください。
2. 実装によってユーザーに見えるものが異なる場合。「どう作ればよいですか？」ではなく、「進捗は言語ごとのグラフ、ファイルごとの表、それとも単一の数値のどれがよいですか？」と尋ねます。
3. **プラットフォームの制約により、ユーザーに妥協を求める場合。**以下を参照してください。

一度に質問は1つだけにし、それぞれ推奨案を添えて、「はい」と答えるだけで済むようにしてください。ユーザーがわからない場合は、推奨案を採用して先に進みます。質問がゼロでも問題ありません。

その後、概要を提示して承認を待ちます。create はユーザーの組織に実際のアプリを登録しますが、delete コマンドはありません。

アプリで何かを記憶する必要がある場合

Crowdin Storage は、Crowdin がインストールごとにホストする、アプリ独自の永続化されたキーと値のストアです。そのため、保存された設定、再読み込み後も残るメモ、チームが共有する状態を、バックエンドなしで構築できます。manifest の scopes に application.storage が必要で、呼び出しは REST プロキシと同様に、現在の閲覧者としてトークンなしで実行されます。利用方法はbuilding-app/storage.mdに記載されています。references/sdk.mdには検証済みのスニペットがあります。

設計上の判断点は、保存方法ではなく、各レコードが誰に属するかです。その答えを強制するのがキーのプレフィックスです。

データの種類	使用するもの	理由
あるユーザー個人のもの：フィルター、下書き、メモ、ユーザーが入力した認証情報	kv.user.*（user: プレフィックス）	プラットフォームによって隠されます。読み取りでも一覧表示でも、他のユーザーのレコードは呼び出し元から見れば存在しません
アプリの各サーフェスの所有物：チームの状態、連携設定、そのサーフェスのチームの認証情報	module:{moduleKey}: の下にあるキー	プラットフォームは、そのモジュールとしてアプリが実行され、そこでのアクセスを許可された閲覧者にのみデータを提供します。マネージャー専用モジュールのレコードが、アプリの他のサーフェスに届くことはありません
アプリがアクセスできる全員に公開するもの、またはアプリのモジュール間で共有するもの	プレフィックスのないキー	保護されません。アプリを利用できる人は誰でも読み取れます。公開プロジェクトの場合は匿名の訪問者も含まれ、サインイン済みの閲覧者は誰でも上書きできます

個人に関するものには user: を、あるサーフェスのチームが所有するものには module: をデフォルトで使います。どちらもプラットフォームによるアクセス制御が適用されるためです。プレフィックスのない共有キーを使うのは、アプリが表示される相手なら誰でも正当に閲覧でき、サインイン済みなら変更もできる値に限ります。これには、アプリのモジュール間で共有する必要があるデータも含まれます。module: のレコードはサーフェス間で共有されないためです。モジュールによる範囲の制限が適用されないのは、アプリのインストーラーだけです。インストーラーはどのサーフェスでもすべてのモジュールのレコードを閲覧できます。ただし、他のユーザーの user: レコードは隠されたままです。この順序が重要なのは、失敗が気づかれにくいためです。1 人でアプリをテストしている間はプレフィックスのないキーも問題なく動作しますが、2 人目のユーザーが加わると、情報が漏えいしたり、上書きされたりします。

設計に影響する事実が 2 つあります。認証されていない閲覧者にはユーザー ID がないため、共有キーは引き続き使えますが、kv.user.* を呼び出すとエラーになります。ユーザー単位の機能を提供する前に、コンテキストの user.id を確認してください。また、アプリをアンインストールすると、すべてのレコードが保持されることなく即座に削除されます。

プラットフォームではできないこと

フロントエンドのみのアプリでは、本当にできないことが3つあります。

• 秘密を明かさずに使うこと。 バックエンドがないため、認証情報を使うコードは閲覧者のブラウザーで実行されます。バンドルに埋め込んだキーは誰でも閲覧でき、ストレージのレコードも、そのスコープで許可された全員に復号された状態で返されます。secret: true であっても同じです。保存してよいのは、アクセスできる全員が知っても問題ない場合に限ります。たとえば、各ユーザーが自分で入力する kv.user.* の認証情報や、そのチームだけが使えるモジュールの module: プレフィックスに保存する連携用チーム認証情報です。どちらの場合も secret: true を指定します。見せるべきでない人にも使わせる必要があるキーは、アプリではなく Crowdin 自体の連携設定に保存してください。
• 外部から呼び出されること。 Webhook、スケジュール、メール、そして Crowdin が HTTP 経由で呼び出すプラットフォームの拡張ポイント（custom-mt、custom-file-format、ai-provider、external-qa-check など。ただし、これらはここで有効なモジュールタイプですらありません）。閉じたタブは何も受信しません。
• タブを閉じた後も処理を続けること。 ブラウザーで数メガバイトのファイルを処理するのは問題ありませんが、数百メガバイトは無理です。

できないことがあっても、作業をそこで終わらせないでください。 ユーザーは実際の作業を抱えています。「バックエンドが必要です」と伝えるだけでは不十分です。実行できる部分を提供し、トレードオフを平易な一文で説明してください。

ユーザーの依頼	提供する内容
毎週のメールダイジェスト	必要なときにユーザーが開くページそのものと、Crowdin 自体の通知設定への案内。メールでの配信はこの種類のアプリではできないと伝えてください
サードパーティ製エンジンまたはキー	見せるべきでない人にも使わせる必要があるキーの場合は、Crowdin 自体の連携設定を案内してください。利用者全員がキーを知っても問題ない場合は、Crowdin Storage に secret: true を付けて保存できます。個人用キーには kv.user.*、チーム用キーには制限付きモジュールの module: プレフィックスを使います
巨大なファイルの処理	合意した上限に収まるサイズで、同じ処理を行います

役に立つことが何も残らない場合に限り、できないと伝え、開発者に引き継ぐことを提案してください。ユーザーの作業を、次の手順として npm パッケージ名を挙げて終わらせてはいけません。

ビルド手順

0. 事前確認

Node ^22.19 || ^24 と pnpm が必要です。npx には Node が必要なので、通常不足するのは pnpm です。corepack enable pnpm を実行してください。Node 自体がインストールされていない場合は、最初にインストールが1回必要だと率直に伝え、ユーザーだけに対処を任せずサポートしてください。

読み取り専用の呼び出しで認証を確認します。

npx @crowdin/serverless-apps-cli@latest list --json

JSON が返ればログイン済みです。Not logged in. Run crowdin-serverless-apps login first. と表示された場合は、先に認証ハンドシェイクを実行してください。

作成を始める前に、アプリを作成する場所を絶対パスで伝えてください。その後の変更はすべてそのディレクトリで行うため、ユーザーがアプリの保存場所を把握している必要があります。

1. スキャフォールド

npx @crowdin/serverless-apps-cli@latest create <name> --template projects-dashboard-cli --yes
cd <name> && pnpm install

どちらのフラグも重要です。指定しないと、CLI はインタラクティブな選択画面で入力待ちとなり、非対話型シェルでは処理が停止します。

必ず projects-dashboard-cli を選んでください。 テンプレートは比較検討するものではなく、質問する価値もありません。このテンプレートを使うと、CLI が Vite、Tailwind、Lingui、Biome、基本の tsconfig を含むツールチェーン全体を管理するため、以降の作業はここに記載したとおりに進められます。projects-dashboard-standalone ではビルド管理をアプリ側に任せることになり、後で問題が起きてもすべて自分で対処する必要があります。ユーザーがビルドを自分で管理したいと明示した場合に限り、こちらを選んでください。

create は .env に CROWDIN_APP_ID を書き込み、アプリを登録します。以降はアプリのディレクトリ内にあるローカルバイナリ、つまり npx crowdin-serverless-apps <command> を使ってください。そうすることで、ツールチェーンのバージョンがアプリで固定されたバージョンと一致します。

2. 配置場所：見落とされがちな問題の原因

スキャフォールドには organization-menu と profile-resources-menu の2つのモジュールが含まれていますが、それぞれが一方のエディションにしか存在しません。ユーザーがどちらのエディションを使っていても、片方は機能せず、表示されることはありません。また、preview でそのモジュールへのリンクを作成することもできません。そのため、最初に行う変更は、ユーザーのエディションに合う方を残し、もう一方を manifest.json と src/index.tsx の両方から削除することです。

アプリを別の場所に配置する場合は、次の2か所を必ずセットで変更します。

• manifest.json - モジュールタイプをキーとする modules マップ
• src/index.tsx - 対応する prepare* 呼び出し。同期処理として、トップレベルに記述します

これらは互いに一致し、ホストから context.app.type で渡される値とも一致している必要があります。一致していないと、SDK は prepare() を呼び出さず、ホストには空白の iframe が表示されますが、コンソールにも原因は表示されません。

エディターモジュールには modes、アセットパネルには fileNamePattern、コンテキストメニューの項目には、配置場所に応じて使用可能な対象が異なる options の3つ組が必要です。ユーザーのプロジェクトにファイルがない場合（文字列ベースのプロジェクト）は、stringBasedAvailable: true に設定してください。デフォルトは false なので、設定しないと、エラーがどこにも表示されないまま、ユーザーのすべてのプロジェクトでアプリが表示されなくなります。

references/modules.md には、各タイプの一覧があります。配置場所の平易な説明、prepare*、追加フィールド、エディションの制限、preview から開けるかどうかが記載されています。

3. UI を作成する

SDK のコードを書く前に references/sdk.md を読んでください。動作するスキャフォールドで検証済みのスニペットと、型チェックでは検出できない落とし穴が記載されています。ユーザーに直接影響する注意点が2つあります。レイアウトを変更した後は必ず resize() を呼び出してください。呼び出さないとアプリが途中で切れて表示されます。また、適切な空の状態を設計してください。初回起動時に TM がない組織や、用語集がないプロジェクトでは画面が真っ白になり、ユーザーには壊れているように見えます。

すべてのアプリはローカライズ可能にする必要があります。これは任意の追加機能ではありません。 スキャフォールドは Lingui、locales/ フォルダー、カタログなど、ローカライズに必要な設定があらかじめ済んでいるため、これを維持するのが基本です。取り除くほうが例外的な対応になります。ユーザーに見える文字列は、後からではなく、書くときにすべてマクロ（<Trans>、<Plural>、t`）で囲んでください。後から対応する場合、JSX のすべての行を再度編集することになります。その後、npx crowdin-serverless-apps extract を実行すると locales/*.po に抽出され、build でもデフォルトで再抽出されます。このアプリは、ユーザーがそれぞれの言語で作業するローカライズプラットフォーム内で動作します。ハードコードされた英語は、ユーザーがすぐに気づく唯一の問題です。

4. ロゴを用意する

スキャフォールドにはプレースホルダーの public/logo.svg が含まれています。これをそのままにしておくと、作業が完了していないことが最もはっきり伝わります。メニュー内のすべてのアプリに、同じ汎用タイルが表示されてしまうためです。アプリの内容を表す図柄を描きましょう。たとえば、翻訳メモリならレイヤー、レポートなら棒グラフ、用語集ならタグです。

プレースホルダーと同じ 0 0 64 64 の正方形の viewBox にし、約24pxで表示されるため、文字は入れないでください。ホストのテーマはライトとダークで切り替わり、CSS は <img> の内部に適用できないため、マークには独自の背景を付けてください。外部フォントや画像を使わず、単独で完結させ、サイズは最大でも数 KB に収めます。public/logo.svg に保存してください。マニフェストはすでに /logo.svg を参照しており、public/ 配下はすべてバンドルに含まれます。その後、dist/logo.svg が存在し、dist/bundle.zip に含まれていることを確認してください。

5. グリーンゲート

pnpm typecheck && pnpm lint
npx crowdin-serverless-apps manifest validate

3つのうち1つでも赤の間は、コードを引き渡さないでください。typecheck は、存在しない SDK API を検出します。typecheck も lint も manifest.json は読み込みません。それを検証するのが manifest validate です。このコマンドはファイルをスキーマと照合し、scopes もコードと照合します。アプリが API クライアント経由で行うすべての呼び出しについて、そのメソッドに必要なスコープと照合し、createStorage() は application.storage と照合して、その結果をマニフェストと比較します。マニフェストでカバーされていない呼び出しがある場合は、追加すべき正確な文字列を示す問題になります。宣言されているのに使われていないスコープは注記になります。検証はオフラインで行われるため、ログインもアプリへのリンクも不要ですが、スコープのチェックでは node_modules 内のパッケージを読み込むため、pnpm install の後、またマニフェストや API 呼び出しを変更するたびに実行してください。問題がある場合は終了コード 1 で終了し、問題をセクションごとにまとめて、その下に fix の行を表示します。このヒントを読んでください。許可されている値が、スコープ文字列も含めて示されています。

scope check skipped の注記があるグリーンの実行では、スコープはチェックされていません。注記に従ってください。pnpm install を実行するか、チェックが導入される前のアプリなら pnpm update @crowdin/serverless-apps-cli @crowdin/crowdin-api-client を実行して、もう一度検証してください（scopes.md）。

検証に合格しても、Crowdin がマニフェストを受け入れるという意味ではありません。簡単なミスが取り除かれただけです。

6. マニフェストを同期する

npx crowdin-serverless-apps manifest status   # exit code 1 means local and remote differ
npx crowdin-serverless-apps manifest push

公開する前に同期してください。公開後ではありません。publish で移動するのはバンドルだけです。modules、scopes、name はプッシュ時にのみ反映されます。preview もディスク上のマニフェストではなく、Crowdin にあるマニフェストを読み込みます。そのため、プッシュしていない変更があると、古い配置をプレビューすることになります。

7. 開発サーバーではなく公開する

npx crowdin-serverless-apps publish -y

ビルドして dist/bundle.zip をアップロードし、Crowdin がそのファイルを配信するように切り替えます。dev は起動しないでください。アプリが自分のマシンに結び付けられ、ユーザーはターミナルを開いたままにする必要があり、すぐに使えるものを渡すという目的に反します。dev は、ユーザー が自分のターミナルで素早くローカルの反復作業をしたい場合に適したツールです。トレードオフを明確に伝えてください。以後、反復のたびに即時のリロードではなく、ビルドとアップロードが必要になります。

8. 表示範囲を最後まで確認する

npx crowdin-serverless-apps list --json

各アプリは解決済みの permissions を報告するため、推測せずに確認してください。新規インストールでは user: owner となります。これは、アプリを作成したユーザーには機能しますが、ほかのユーザーには表示されないことを意味します。また、create によって編集前にアプリがインストールされているため、後からマニフェストで default_permissions を設定しても、既存のインストールに適用範囲は広がりません。

そのため、依頼内容から対象ユーザーを判断してください（「翻訳者に見えるようにする」なら all、ベンダーページなら guests、コストレポートなら owner）。list --json の報告内容より広い権限が必要な場合は、Crowdin アプリマネージャーまでの手順を、わかりやすい言葉でユーザーに案内してください。これを省略すると、すべてがグリーンでも実行が失敗に終わることがあります。リンクを共有したのに同僚には何も表示されず、アプリが壊れているように見えてしまいます。

呼び出しは閲覧者として実行されることを忘れないでください。翻訳者向けのアプリは、翻訳者に許可されている操作だけで動作する必要があります。そうでなければ、まさにそのアプリの対象者に 403 が返されます。

9. 開いて確認する

npx crowdin-serverless-apps preview --module <key> [--project <id|identifier>]

必ず --module を指定してください。モジュールが複数あり、フラグを指定しない場合、CLI はどれを選ぶか決められず処理を拒否します。プロジェクトモジュールと editor-right-panel にはプロジェクトの指定が必要です。--project を省略すると、ログインユーザーがアクセスできる最初のプロジェクトが使われます。簡易テストには問題ありませんが、コンテンツがプロジェクトに依存する場合は誤りです。そのため、ユーザーのリンクに記載されたプロジェクトを指定してください。

18 種類のうち 7 種類には開くページがありません。該当するのは、editor-right-panel 以外の 3 つのエディタータイプと、modal、chat、context-menu、navbar-extension です。これらの場合、preview は代替表示に切り替わらず、エラーになります。これは想定された動作であり、バグではありません。リンクの代わりに、簡単なナビゲーション手順を案内してください。このような配置のひな形を作る前に、そのことをユーザーに伝え、リンク可能な代替案を提案してください。

その後、必ず検証してください。ここまでの作業だけでは、アプリが表示されることは何も証明されていません。typecheck、lint、publish のいずれも、空白の iframe、403 エラー、表示が切れたパネル、空の画面は検出できません。ブラウザーを操作できる場合は、リンクを開いてアプリが描画されることと、コンソールにエラーがないことを確認してください。できない場合は、未検証であることを明確に伝え、リンクを開いて表示内容を知らせてもらってください。URL が表示されたというだけで成功を報告してはいけません。

リンクは、メッセージ内でクリック可能な形式で渡してください。preview が開くブラウザーはあなたの環境のものであり、ユーザーの環境とは限りません。

認証ハンドシェイク

ログインはブラウザーでの OAuth フローであり、ユーザーの操作が必要です。出力を確認しながら待てるよう、バックグラウンドで開始してください。

npx @crowdin/serverless-apps-cli@latest login

対話型でないシェルでは、認証 URL がプレーンテキストで出力されます。例：open this link (https://accounts.crowdin.com/oauth/authorize?...)。URL を取り出してクリック可能なリンクとして渡してください。CLI がブラウザーを開こうとしても、あなたの環境では何も起こらない場合があります。CLI は 5 分間待機してから終了します。そのことを伝え、ユーザーが席を外していた場合は、再度開始してください。

チャットでトークンを尋ねてはいけません。ブラウザーがまったくないマシンでは、環境変数 CROWDIN_PERSONAL_TOKEN を使えます。

問題が発生した場合

表示される内容	意味
Not logged in. Run crowdin-serverless-apps login first.	認証ハンドシェイクです。
create で CLI が何も出力せず停止する	--template または --yes が指定されていないため、選択画面で待機しています。
This app declares 2 modules. Pass --module <key>	変更されていないひな形です。このエディションで使用されていないモジュールを削除してから、キーを渡してください。
Module type X only has a page on Crowdin Enterprise / only on crowdin.com	エディションによる配置制限です。利用者のエディションで使えるものを選んでください。
Module type X has no page of its own	開けない7種類のうちの1つです。想定される動作は、リンクではなくナビゲーションを引き継ぐことです。
iframe が空白になる、またはホストにアプリが起動しなかったと報告される	マニフェストのタイプ、prepare*、context.app.type が一致していないか、登録情報がトップレベルにないか、同じタイプのモジュールがキーなしで2つあります。
アプリは公開済みだが、UI スロットに表示されない	manifest push がスキップされたか、文字列ベースのプロジェクトに stringBasedAvailable がありません。
アプリは開くが何も表示されない	データが空か、最初のプロジェクトへのフォールバック先に用語集／TM／文字列がありません。コードを疑う前に確認してください。
実行時に 403 Endpoint isn't allowed for token scopes. が発生する	マニフェストのスコープの問題です。manifest validate を実行すると、対象の呼び出しと追加する文字列が示されます。検証に問題がない場合は manifest status を実行してください。スコープはディスク上にありますが、プッシュされていません。scope check skipped と表示された場合は、まず注記の指示に従ってください。その注記が表示された状態で検証に問題がなくても、スコープは確認されていません（scopes.md）。
その他の 403、またはすべてのチェックに問題がないのにリストが空	マニフェストではなく、閲覧者自身の権限の問題です。呼び出しはアプリを開いたユーザーとして実行され、どのチェックでもその権限は確認できません。そのユーザーに許可されている操作を前提に構築するか、対象ユーザーを絞ってください。
すべてのストレージ呼び出しが拒否される	マニフェストの scopes に application.storage がありません。manifest validate を実行すると、スコープが必要な createStorage() 呼び出しが示されます。検証に問題がない場合は、マニフェストの変更がプッシュされていません。
共有キーは動作するのに kv.user.* がエラーになる	閲覧者が匿名で、ユーザー ID がありません。ユーザーごとの機能を提供する前に、コンテキストの user.id を確認してください。
module:...: で始まるキーへの書き込みが拒否される	キーが、アプリの現在の実行先とは異なるモジュール、または不明なモジュールを指定しています。同じ状況でも読み取り時はエラーにならず、get は undefined に解決され、一覧ではレコードがスキップされます。
You have no accessible projects to preview this module in.	プロジェクトにアクセスできないか、公開プロジェクトを必要とするクラウドソーシングモジュールです。
Could not list your projects - this login may lack the project scope.	再度ログインして、スコープを付与してください。
GraphQL is not available to serverless apps	プロキシは REST の /api/v2 のみに対応しています。
FormData bodies are not supported through AP.apiRequest	生の Blob、File、または ArrayBuffer を渡してください。
manifest push が Crowdin に拒否される	manifest validate を実行してください。問題のパスが示されます。
ネットワークまたは権限が原因で npx が失敗する	CLI ではなく、環境の問題です。ユーザーに許可を依頼してください。

参考資料

• references/modules.md - すべてのモジュールタイプ：配置、prepare*、マニフェストのフィールド、エディション制限、preview で開けるもの
• references/sdk.md - 検証済みの SDK スニペットと、型チェックで検出できない落とし穴
• references/scopes.md - manifest validate がコードからスコープを導き出す方法と、検出できない内容
• references/cli.md - コマンドとフラグのリファレンス、環境変数、各コマンドが書き込む内容