[docs/korean] Translate official document into Korean / except pages that alstn2468 translated

docs/docs_kr/api-reference/core/Loadable.md

@@ -0,0 +1,34 @@
+---
+title: class Loadable
+sidebar_label: Loadable
+---
+
+`Lodable` 객체는 Recoil [atom](/docs/api-reference/core/atom) 혹은 [selector](/docs/api-reference/core/selector)의 최신 상태를 대표합니다. 이 상태는 사용가능한 값을 가지고 있거나 에러 상태이거나 혹은 여전히 비동기 해결 보류 중일 수 있습니다. `Lodable` 은 다음의 인터페이스를 가집니다.
+
+- `state`: atom 혹은 selector의 최신 상태입니다. 가능한 값은 '`hasValue`', '`hasError`', 혹은 '`loading`' 입니다.
+- `contents`: `Lodable`에 의해서 대표되는 값입니다. 만약 상태가 `hasValue` 라면, 이는 실제 값입니다. 만약 상태가 `hasError` 라면 이는 던져진 Error 객체입니다. 그리고 만약 상태가 'loading'이라면 `toPromise()`를 사용하여 값의 `Promise`를 얻을 수 있습니다.
+
+Lodable은 최신 상태에 접근하기 위한 도우미 메서드를 가지고 있습니다. *이 API는 아직 불안정합니다:*
+
+- `getValue()` - React Suspense와 Recoil selectors의 시맨틱에 매치되는 값에 접근하기 위한 메서드. 만약 상태가 값을 가지고 있다면 값을 리턴하며, error를 가지고 있다면 해당 error를 던집니다. 만약 여전히 보류중이라면 실행을 연기하거나 보류중인 상태를 전파하기 위해 리렌더링합니다.
+- `toPromise()`: selector가 resolve되면 resolve될 `Promise` 를 리턴합니다. selector가 동기이거나 이미 resolve된 상태라면, 즉시 resolve 되는 `Promise` 를 리턴합니다.
+- `valueMaybe()` - 가능하다면 값을 리턴하며 다른 경우에는 `undefined` 를 리턴합니다.
+- `valueOrThrow()` - 가능하다면 값을 리턴하거나 Error를 던집니다.
+- `map()` - Lodable의 값을 변형하기 위한 함수를 받으며 새로운 Lodable을 변형된 값과 함께 리턴합니다. 변형 함수는 값의 매개변수를 받아 새로운 값을 리턴합니다; 던져진 에러나 suspense를 전파할 수도 있습니다.
+
+### Example
+
+```jsx
+function UserInfo({userID}) {
+  const userNameLoadable = useRecoilValueLoadable(userNameQuery(userID));
+  switch (userNameLoadable.state) {
+    case 'hasValue':
+      return <div>{userNameLoadable.contents}</div>;
+    case 'loading':
+      return <div>Loading...</div>;
+    case 'hasError':
+      throw userNameLoadable.contents;
+  }
+}
+```
+

docs/docs_kr/api-reference/core/RecoilRoot.md

@@ -0,0 +1,30 @@
+---
+title: <RecoilRoot ...props />
+sidebar_label: <RecoilRoot />
+---
+
+Provides the context in which atoms have values. Must be an ancestor of any component that uses any Recoil hooks. Multiple roots may co-exist; atoms will have distinct values within each root. If they are nested, the innermost root will completely mask any outer roots.
+
+---
+
+**Props**:
+- `initializeState?`: `(MutableSnapshot => void)`
+  - An optional function that takes a [`MutableSnapshot`](/docs/api-reference/core/Snapshot#transforming-snapshots) to [initialize](/docs/api-reference/core/Snapshot#state-initialization) the `<RecoilRoot>` atom state.  This sets up the state for the initial render and is not intended for subsequent state changes or async initialization.  Use hooks such as [`useSetRecoilState()`](/docs/api-reference/core/useSetRecoilState) or [`useRecoilCallback()`](/docs/api-reference/core/useRecoilCallback) for async state changes.
+
+---
+
+`<RecoilRoot>`'s represent independent providers/stores of atom state.  Note that caches, such as selector caches, may be shared across roots.  Selector evaluations must be idempotent except for caching or logging, so this should not be a problem, but may be observable or may cause redundant queries to be cached across roots.
+
+### Example
+
+```jsx
+import {RecoilRoot} from 'recoil';
+
+function AppRoot() {
+  return (
+    <RecoilRoot>
+      <ComponentThatUsesRecoil />
+    </RecoilRoot>
+  );
+}
+```

docs/docs_kr/api-reference/core/Snapshot.md

@@ -0,0 +1,119 @@
+---
+title: class Snapshot
+sidebar_label: Snapshot
+---
+
+Snapshot 객체는 Recoil [atom](/docs/api-reference/core/atom)의 상태의 변경불가능한 스냅샷을 나타냅니다. 전역 Recoil 상태를 관찰, 검사, 관리하기 위한 API를 표준화 하기 위한 것입니다. 이는 개발툴, 전역 상태 동기화, 히스토리 탐색 등에 유용합니다.
+
+```jsx
+class Snapshot {
+  // Accessors to inspect snapshot state
+  getLoadable: <T>(RecoilValue<T>) => Loadable<T>;
+  getPromise: <T>(RecoilValue<T>) => Promise<T>;
+
+  // API to transform snapshots for transactions
+  map: (MutableSnapshot => void) => Snapshot;
+  asyncMap: (MutableSnapshot => Promise<void>) => Promise<Snapshot>;
+
+  // Developer Tools API
+  getID: () => SnapshotID;
+  getNodes_UNSTABLE: ({
+    isModified?: boolean,
+  } | void) => Iterable<RecoilValue<mixed>>;
+  getInfo_UNSTABLE: <T>(RecoilValue<T>) => {...};
+}
+
+function snapshot_UNSTABLE(initializeState?: (MutableSnapshot => void)): Snapshot
+```
+
+## Obtaining Snapshots
+
+### Hooks
+
+Recoil은 다음의 hook을 현재의 상태를 기반으로 스냅샷을 얻기 위해 제공합니다:
+
+- [`useRecoilCallback()`](/docs/api-reference/core/useRecoilCallback) - 스냅샷에 비동기 엑세스
+- [`useRecoilSnapshot()`](/docs/api-reference/core/useRecoilSnapshot) - 스냅샷에 동기 엑세스
+- [`useRecoilTransactionObserver_UNSTABLE()`](/docs/api-reference/core/useRecoilTransactionObserver) - 모든 상태 변경에 대해서 Snapshot을 구독
+
+### Building a Snapshot
+
+선택적 초기화 함수를 허용하는 `snapshot_UNSTABLE()` 팩토리를 사용하여 새로운 스냅샷을 빌드 할 수도 있습니다. 이는 React context 외부의 selector의 [테스트](/docs/guides/testing)와 평가에 사용될 수 있습니다.
+
+## Reading Snapshots
+
+스냅샷은 atom 상태에 관련하여 읽기 전용입니다. 이들은 atom 상태를 읽고 selector의 파생된 상태를 평가하기 위해서 사용될 수 있습니다. `getLoadable()`은 이 스냅샷의 atom 혹은 selector의 상태와 함께 [Loadable](/docs/api-reference/core/Loadable)을 제공합니다. `getPromise()` 메서드는 정적 atom 상태를 기반으로 하는 값을 확인 하기 위해 비동기 selector의 평가된 값을 대기하기 위해 사용될 수 있습니다.
+
+### Example
+
+```jsx
+function MyComponent() {
+  const logState = useRecoilCallback(({snapshot}) => () => {
+    console.log("State: ", snapshot.getLoadable(myAtom).contents);
+
+    const newSnapshot = snapshot.map(({set}) => set(myAtom, 42));
+  });
+}
+```
+
+## Transforming Snapshots
+
+스냅샷을 변경하고 싶은 경우가 있을 수 있습니다. 스냅샷은 변경이 불가능하지만 변환 집합을 사용하여 새로운 변경불가능한 스냅샷으로 스냅샷 자신을 매핑하는 방법이 있습니다. 매핑 메서드는 콜백을 통해 변경되며 궁극적으로 매핑 작업에서 리턴되는 새로운 스냅샷이 될 MutableSnapshot을 전달받은 콜백을 받습니다.
+
+```jsx
+class MutableSnapshot {
+  set: <T>(RecoilState<T>, T | DefaultValue | (T => T | DefaultValue)) => void;
+  reset: <T>(RecoilState<T>) => void;
+}
+```
+
+`set()` 과 `reset()`은 쓰기 가능한 selector의 set 프로퍼티에 제공된 콜백과 같은 시그니쳐를 가집니다. 하지만 현재 상태가 아닌 새로운 스냅샷에만 영향을 줍니다.
+
+## Going to a Snapshot
+
+다음의 hook은 현재 Recoil 상태를 제공된 `Snapshot`으로 네비게이트 할 수 있습니다:
+- [`useGotoRecoilSnapshot()`](/docs/api-reference/core/useGotoRecoilSnapshot) - 현재의 상태를 Snapshot에 일치하게 업데이트
+
+
+## Developer Tools
+
+Snapshots provide some methods useful for [building developer tools](/docs/guides/dev-tools) or debugging capabilities with Recoil.  This API is still evolving, and thus marked as `_UNSTABLE`, as we work on the initial dev tools.
+
+### Snapshot IDs
+
+커밋된 각각의 상태 혹은 변경된 스냅샷은 `getID()`를 통해 얻을 수 있는 고유한 불투명 버전의 ID를 갖습니다. 이는 `useGotoRecoilSnapshot()`을 통해 이전 스냅샷으로 돌아갔을 때 이를 감지하기 위해서 사용할 수 있습니다.
+
+### Enumerate Atoms and Selectors
+
+`getNodes_UNSTABLE()` 메서드는 이 스냅샷에서 사용된 모든 atom과 selector를 나열하는데에 사용할 수 있습니다. Atom, selector, 그리고 families는 언제든 생성될 수 있으나, 실제로 사용되었을 때에만 스냅샷에 나타납니다. Atom과 selector는 더 이상 사용되지 않을 경우 후속 상태 스냅샷에서 제거될 수 있습니다.
+
+선택적 `isModified` 플래그는 마지막 트랜잭션 이후 수정 된 atom만 리턴 할 수 있도록 지정할 수 있습니다.
+
+### Debug information
+
+`getInfo_UNSTABLE()` 메서드는 atom과 selector에 대한 추가적인 디버그 정보를 제공합니다. 디버그 정보 부분은 발전 중이지만 다음을 포함할 수 있습니다:
+
+* `loadable` - 현재 상태의 Loadable. `getLoadable()` 같은 메서드와 다르게 이 메서드는 스냅샷을 전혀 변경하지 않습니다. 현재 상태를 제공하며, 새로운 atom/selector를 초기화하거나 새로운 selector 평가를 수행하거나, 의존성 혹은 구독을 업데이트 하지 않습니다.
+* `isSet` - 이것이 스냅샷 상태에 저장된 명시적인 값을 가진 atom이라면 True입니다.
+* `isModified` - 마지막 트랜젝션 이후로 수정된 atom이라면 True입니다.
+* `type` - `atom` 혹은 `selector`
+* `deps` - 이 노드가 의존하는 atom 혹은 selector에 대한 iterator입니다.
+* `subscribers` - 이 스냅샷에 대해서 이 노드를 구독하는 항목에 대한 정보입니다. 세부사항은 개발중입니다.
+
+## State Initialization
+
+[`<RecoilRoot>`](/docs/api-reference/core/RecoilRoot) 컴포넌트와 `snapshot_UNSTABLE()` 팩토리는 `MutableSnapshot`을 통해 상태를 초기화하기 위한 선택적인 `initializeState` prop을 취합니다. 이는 모든 atom을 미리 알고 있고, 상태가 동기적으로 설정되어야하는 서버사이드렌더링과 호환되는 경우 지속되는 상태를 로딩하는데에 유용할 수 있습니다. atom 별 초기화/지속성 그리고 동적 atom과의 작업의 용이성을 위해 [atom effects](/docs/guides/atom-effects)를 고려해야합니다.
+
+```jsx
+function MyApp() {
+  function initializeState({set}) {
+    set(myAtom, 'foo');
+  }
+
+  return (
+    <RecoilRoot initializeState={initializeState}>
+      ...
+    </RecoilRoot>
+  );
+}
+```

docs/docs_kr/api-reference/core/atom.md

@@ -0,0 +1,65 @@
+---
+title: atom(options)
+sidebar_label: atom()
+---
+
+An *atom* represents state in Recoil.  The `atom()` function returns a writeable `RecoilState` object.
+
+---
+
+```jsx
+function atom<T>({
+  key: string,
+  default: T | Promise<T> | RecoilValue<T>,
+
+  effects_UNSTABLE?: $ReadOnlyArray<AtomEffect<T>>,
+
+  dangerouslyAllowMutability?: boolean,
+}): RecoilState<T>
+```
+
+  - `key` - A unique string used to identify the atom internally. This string should be unique with respect to other atoms and selectors in the entire application.
+  - `default` - The initial value of the atom or a `Promise` or another atom or selector representing a value of the same type.
+  - `effects_UNSTABLE` - An optional array of [Atom Effects](/docs/guides/atom-effects) for the atom.
+  - `dangerouslyAllowMutability` - In some cases it may be desireable allow mutating of objects stored in atoms that don't represent state changes.  Use this option to override freezing objects in development mode.
+
+---
+
+Recoil manages atom state changes to know when to notify components subscribing to that atom to re-render, so you should use the hooks listed below to change atom state.  If an object stored in an atom was mutated directly it may bypass this and cause state changes without properly notifying subscribing components.  To help detect bugs Recoil will freeze objects stored in atoms in development mode.
+
+Most often, you'll use the following hooks to interact with atoms:
+
+- [`useRecoilState()`](/docs/api-reference/core/useRecoilState): Use this hook when you intend on both reading and writing to the atom. This hook subscribes the component to the atom.
+- [`useRecoilValue()`](/docs/api-reference/core/useRecoilValue): Use this hook when you intend on only reading the atom. This hook subscribes the component to the atom.
+- [`useSetRecoilState()`](/docs/api-reference/core/useSetRecoilState): Use this hook when you intend on only writing to the atom.
+- [`useResetRecoilState()`](/docs/api-reference/core/useResetRecoilState): Use this hook to reset an atom to its default value.
+
+For rare cases where you need to read an atom's value without subscribing to the component, see [`useRecoilCallback()`](/docs/api-reference/core/useRecoilCallback).
+
+You can initialize an atom either with a static value or with a `Promise` or a `RecoilValue` representing a value of the same type.  Because the `Promise` may be pending or the default selector may be asynchronous it means that the atom value may also be pending or throw an error when reading.  Note that you cannot currently assign a `Promise` when setting an atom.  Please use [selectors](/docs/api-reference/core/selector) for async functions.
+
+Atoms cannot be used to store `Promise`'s or `RecoilValue`'s directly, but they may be wrapped in an object.  Note that `Promise`'s may be mutable.  Atoms can be set to a `function`, as long as it is pure, but to do so you may need to use the updater form of setters. (e.g. `set(myAtom, () => myFunc);`).
+
+### Example
+
+```jsx
+import {atom, useRecoilState} from 'recoil';
+
+const counter = atom({
+  key: 'myCounter',
+  default: 0,
+});
+
+function Counter() {
+  const [count, setCount] = useRecoilState(counter);
+  const incrementByOne = () => setCount(count + 1);
+
+  return (
+    <div>
+      Count: {count}
+      <br />
+      <button onClick={incrementByOne}>Increment</button>
+    </div>
+  );
+}
+```

docs/docs_kr/api-reference/core/isRecoilValue.md

@@ -0,0 +1,34 @@
+---
+title: isRecoilValue(value)
+sidebar_label: isRecoilValue()
+---
+
+Returns `true` if `value` is either an atom or selector and `false` otherwise.
+
+```jsx
+function isRecoilValue(value: mixed): boolean
+```
+
+---
+
+### Example
+
+```jsx
+import {atom, isRecoilValue} from 'recoil';
+
+const counter = atom({
+  key: 'myCounter',
+  default: 0,
+});
+
+const strCounter = selector({
+  key: 'myCounterStr',
+  get: ({get}) => String(get(counter)),
+});
+
+isRecoilValue(counter); // true
+isRecoilValue(strCounter); // true
+
+isRecoilValue(5); // false
+isRecoilValue({}); // false
+```