Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: german translations #544

Closed
wants to merge 2 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 146 additions & 0 deletions docs/.vitepress/config/de.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'

export const deConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
themeConfig: {
editLink: {
pattern: 'https://github.com/tresjs/tres/edit/main/packages/docs/:path',
text: 'Änderungen an dieser Seite vorschlagen',
},
sidebar: [
{
text: 'Anleitung',
items: [
// Dies zeigt die Seite `/guide/index.md`.
{ text: 'Einführung', link: '/de/guide/' },
{ text: 'Loslegen', link: '/de/guide/getting-started' },
{ text: 'Deine erste Szene', link: '/de/guide/your-first-scene' },
{ text: 'Nuxt', link: '/de/guide/nuxt' },
{ text: 'Fehlerbehebung', link: '/de/guide/troubleshooting' },
{ text: 'Migration von v1', link: '/de/guide/migration-guide' },
],
},
{
text: 'API',
items: [
{ text: 'TresCanvas', link: '/de/api/tres-canvas' },
{
text: 'Instanzen, Argumente und Props',
link: '/de/api/instances-arguments-and-props',
},
{
text: 'Composables',
link: '/de/api/composables',
},
{
text: 'Ereignisse',
link: '/de/api/events',
},
],
},

{
text: 'Fortgeschritten',
items: [
{ text: 'Erweitern', link: '/de/advanced/extending' },
{ text: 'Primitive', link: '/de/advanced/primitive' },
{
text: 'Warnhinweise',
link: '/de/advanced/caveats',
},
],
},
{
text: 'Debugging',
items: [
{ text: 'Entwicklungstools', link: '/de/debug/devtools' },
],
},
{
text: 'Beispiele',
collapsed: true,
items: [
{ text: 'Orbit-Kontrollen', link: '/de/examples/orbit-controls' },
{ text: 'Grundlegende Animationen', link: '/de/examples/basic-animations' },
{ text: 'Gruppen', link: '/de/examples/groups' },
{ text: 'Texturen laden', link: '/de/examples/load-textures' },
{ text: 'Modelle laden', link: '/de/examples/load-models' },
{ text: 'Text laden', link: '/de/examples/text-3d' },
{ text: 'Lichter und Schatten', link: '/de/examples/lights-shadows' },
{ text: 'Shaders', link: '/de/examples/shaders' },
],
},
{
text: 'Direktiven',
collapsed: true,
items: [
{ text: 'v-log', link: '/de/directives/v-log' },
{ text: 'v-light-helper', link: '/de/directives/v-light-helper' },
{ text: 'v-always-look-at', link: '/de/directives/v-always-look-at' },
{ text: 'v-distance-to', link: '/de/directives/v-distance-to' },
],
},
{
text: 'Ökosystem',
items: [
{
text: 'Cientos 💛',
link: 'https://cientos.tresjs.org/',
},
{
text: 'Nuxt-Modul',
link: 'https://github.com/Tresjs/nuxt',
},
{
text: 'TresLeches 🍰',
link: 'https://tresleches.tresjs.org/',
},
{
text: 'Nachbearbeitung (Demnächst)',
},
],
},
],
nav: [
{ text: 'Anleitung', link: '/de/guide/' },
{ text: 'API', link: '/de/api/tres-canvas' },
/* { text: 'API', link: '/de/api/' },
{ text: 'Konfiguration', link: '/de/config/' }, */
{
text: 'Ressourcen',
items: [
{ text: 'Team', link: '/de/team' },
{ text: 'Versionen', link: 'https://github.com/Tresjs/tres/releases' },
{
text: 'Spielplatz',
link: 'https://playground.tresjs.org/',
},
{
text: 'Github',
link: 'https://github.com/Tresjs/tres/',
},
{
text: 'Probleme',
link: 'https://github.com/Tresjs/tres/issues',
},
{
text: 'Ökosystem',
items: [
{
text: 'Hunderte 💛',
link: 'https://cientos.tresjs.org/',
},
{
text: 'Nuxt-Modul',
link: 'https://github.com/Tresjs/nuxt',
},
{
text: 'TresLeches 🍰',
link: 'https://tresleches.tresjs.org/',
},
],
},
],
},
],
},
}
2 changes: 2 additions & 0 deletions docs/.vitepress/config/index.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { defineConfig } from 'vitepress'
import { enConfig } from './en'
import { esConfig } from './es'
import { deConfig } from './de'
import { sharedConfig } from './shared'

/* import { zhConfig } from './zh' */
Expand All @@ -11,6 +12,7 @@ export default defineConfig({
locales: {
root: { label: 'English', lang: 'en-US', link: '/', ...enConfig },
es: { label: 'Español', lang: 'es-ES', link: '/es/', ...esConfig },
de: { label: 'Deutsch', lang: 'de-DE', link: '/de/', ...deConfig },
/* zh: { label: '简体中文', lang: 'zh-CN', link: '/zh/', ...zhConfig }, */
},
})
120 changes: 120 additions & 0 deletions docs/de/advanced/caveats.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
# Avisos 😱

Nuestro objetivo es proporcionar una forma sencilla de utilizar ThreeJS en VueJS con la mejor experiencia de desarrollo posible. Sin embargo, hay algunas advertencias de las que debes ser consciente.

## ~~HMR y ThreeJS~~

:::info

Esto se ha solucionado en **TresJS** v1.7.0 🎉. Ahora puedes utilizar HMR sin tener que recargar la página 🥹.

:::

La sustitución de módulos en caliente (HMR) es una característica que te permite actualizar tu código sin recargar la página. Esta es una gran característica que hace que el desarrollo sea mucho más rápido. **TresJS** utiliza [Vite](https://vitejs.dev/). Sin embargo, es realmente complicado hacer que funcione correctamente con ThreeJS.

¿Por qué? Porque Tres construye la escena de forma declarativa. Esto significa que crea la instancia y la añade a la escena cuando se monta el componente. La complejidad radica en saber cuándo quitar la instancia de la escena y cuándo añadirla de nuevo.

Aunque se ha implementado un flujo de eliminación mínimo, no es perfecto. Esto significa que a veces tendrás que recargar la página para ver los cambios correctamente, especialmente cuando estás haciendo referencia a instancias utilizando [Template Refs](https://v3.vuejs.org/guide/component-template-refs.html)

```vue
<script setup lang="ts">
const boxRef: Ref<TresInstance | null> = ref(null)

onLoop(({ _delta, elapsed }) => {
if (boxRef.value) {
boxRef.value.rotation.y += 0.01
boxRef.value.rotation.z = elapsed * 0.2
}
})
</script>

<template>
<TresMesh
ref="boxRef"
:scale="1"
cast-shadow
>
<TresBoxGeometry :args="[1, 1, 1]" />
<TresMeshStandardMaterial color="teal" />
</TresMesh>
</template>
```

Si realizas un cambio en el `color` del componente `TresMeshStandardMaterial`, verás que el cambio se aplica pero la rotación ya no funciona. Esto se debe a que la instancia se elimina y se crea de nuevo.

:::tip
Entonces, como **regla general**, debes recargar la página cuando no veas los cambios que has realizado.
:::

Dicho esto, estamos trabajando en una mejor solución para esto 😁. Si tienes alguna idea de cómo resolverlo, por favor avísanos.

Puedes seguir la discusión en [HMR Disposal Discussion](https://github.com/Tresjs/tres/issues/23)

## Reactividad

Todos amamos la reactividad 💚. Es una de las características más poderosas de VueJS. Sin embargo, debemos tener cuidado al usar ThreeJS.

La reactividad de Vue se basa en [Proxy](https://developer.mozilla.org/es/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Esto permite que Vue 3 rastree automáticamente los cambios en los objetos de datos y actualice los elementos DOM correspondientes cada vez que los datos cambien.

Dado que estamos renderizando una escena y actualizándola en cada fotograma (60FPS), eso significa que estamos actualizando la escena 60 veces por segundo. Si el objeto a actualizar es reactivo, Vue intentará actualizar ese objeto tantas veces. Esto no es una buena idea 😅 y será perjudicial para el rendimiento.

Aquí tienes una prueba de rendimiento de la diferencia entre usar un objeto Proxy y un objeto plano.

<figure>
<img src="/proxy-benchmark.png" alt="Proxy vs Plain" style="width:100%">
<figcaption>Fig.1 - Ejecuciones por segundo Objeto Plano vs Proxy. </figcaption>
</figure>

Fuente: [Proxy vs Plain Object](https://www.measurethat.net/Benchmarks/Show/12503/0/object-vs-proxy-vs-proxy-setter)

Si te ves obligado a usar reactividad, utiliza [shallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref)

A diferencia de `ref()`, el valor interno de un shallow ref se almacena y se expone tal cual, y no se hace reactividad profunda. Solo el acceso a `.value` es reactivo. Fuente [VueJS Docs](https://vuejs.org/api/reactivity-advanced.html#shallowref)

### Ejemplo

❌ Incorrecto

```vue
<script setup lang="ts">
const position = reactive({ x: 0, y: 0, z: 0 })

onLoop(({ _delta, elapsed }) => {
position.x = Math.sin(elapsed * 0.1) * 3
})
</script>

<template>
<TresMesh
:position="position"
cast-shadow
>
<TresBoxGeometry :args="[1, 1, 1]" />
<TresMeshStandardMaterial color="teal" />
</TresMesh>
</template>
```

✅ Correcto

```vue
<script setup lang="ts">
const position = { x: 0, y: 0, z: 0 }
const boxRef: ShallowRef<TresInstance | null> = shallowRef(null)

onLoop(({ _delta, elapsed }) => {
boxRef.value.position.x = Math.sin(elapsed * 0.1) * 3
})
</script>

<template>
<TresMesh
ref="boxRef"
:position="position"
cast-shadow
>
<TresBoxGeometry :args="[1, 1, 1]" />
<TresMeshStandardMaterial color="teal" />
</TresMesh>
</template>
```
44 changes: 44 additions & 0 deletions docs/de/advanced/extending.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# Extender 🔌

Tres ofrece la funcionalidad básica, pero es fácil agregar elementos de terceros y extenderlos en su catálogo interno.

La mayoría de las experiencias en 3D utilizan `OrbitControls`, que no forma parte de la biblioteca principal. Puedes agregarlo a tu proyecto importándolo desde el módulo `three/addons/controls/OrbitControls`.

```js
import { OrbitControls } from 'three/addons/controls/OrbitControls'
```

## Extender un elemento dinámicamente

También puedes agregarlo dinámicamente en tus componentes:

```vue {2,3,4,7,13,15}
<script setup lang="ts">
import { extend } from '@tresjs/core'
import { OrbitControls } from 'three/addons/controls/OrbitControls'
import { TextGeometry } from 'three/addons/geometries/TextGeometry'

// Añadimos OrbitControls al catalogo interno
extend({ TextGeometry, OrbitControls })
</script>

<template>
<TresCanvas
shadows
alpha
>
<TresPerspectiveCamera :position="[5, 5, 5]" />
<TresOrbitControls
v-if="state.renderer"
:args="[state.camera, state.renderer?.domElement]"
/>
<TresMesh>
<TresTextGeometry
:args="['TresJS', { font, ...fontOptions }]"
center
/>
<TresMeshMatcapMaterial :matcap="matcapTexture" />
</TresMesh>
</TresCanvas>
</template>
```
47 changes: 47 additions & 0 deletions docs/de/advanced/primitive.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Primitives

El componente `<primitive />` es un componente versátil de bajo nivel en TresJS que te permite utilizar directamente cualquier objeto de three.js dentro de tu aplicación Vue sin una abstracción. Actúa como un puente entre el sistema de reactividad de Vue y el grafo de escena de three.js.

## Usage

```html
<script setup lang="ts">
// Importa las clases necesarias de three.js
import { Mesh, BoxGeometry, MeshBasicMaterial } from 'three';

// Crea una geometría de caja y un material básico
const geometry = new BoxGeometry(1, 1, 1);
const material = new MeshBasicMaterial({ color: 0x00ff00 });

// Crea un mesh con la geometría y el material
const meshWithMaterial = new Mesh(geometry, material);
</script>

<template>
<TresCanvas>
<primitive :object="meshWithMaterial" />
</TresCanvas>
</template>
```

## Props

`object`: Esta propiedad espera un objeto `Object3D` de three.js o cualquiera de sus clases derivadas. Es el objeto principal que el componente `<primitive />` renderizará. En el ejemplo actualizado, se pasa un objeto `Mesh` con su correspondiente `Material` a esta propiedad.

## Uso con Modelos

El componente `<primitive />` es especialmente útil para renderizar objetos complejos como modelos cargados desde fuentes externas. El siguiente ejemplo muestra cómo cargar un modelo desde un archivo GLTF y renderizarlo utilizando el componente `<primitive />`.

```html
<script lang="ts" setup>
import { useGLTF } from '@tresjs/cientos'

const { nodes } = await useGLTF('/models/AkuAku.gltf')
</script>

<TresCanvas>
<Suspense>
<primitive :object="nodes.AkuAku" />
</Suspense>
</TresCanvas>
```
Loading